# Home | Plaid Docs

Welcome to the Docs 
====================

#### Here you'll find guides, resources, and references to build with Plaid. 

(An image of "Decorative image of a Abe Lincoln enjoying an energy drink")

#### Quickstart 

Learn about Plaid's key concepts and run starter code

[Get started](https://plaid.com/docs/quickstart/index.html.md)

#### API Reference 

Explore server-side API libraries and integrate with API endpoints

[View reference](https://plaid.com/docs/api/index.html.md)

#### Link 

Link, Plaid's client-side component, helps your users connect their accounts

[Build with Link](https://plaid.com/docs/link/index.html.md)

#### Payments and Funding 

#### Auth 

[Retrieve bank account information for ACH, wire, and other bank-to-bank transfers.](https://plaid.com/docs/auth/index.html.md)

#### Balance 

[Retrieve real-time balance information to prevent ACH returns.](https://plaid.com/docs/balance/index.html.md)

#### Identity 

[Verify users' financial account ownership and reduce fraud.](https://plaid.com/docs/identity/index.html.md)

#### Signal 

[Reduce fraud and provide instant funds access by assessing the return risk of an ACH debit transaction.](https://plaid.com/docs/signal/index.html.md)

#### Transfer 

[Send and receive money end to end with Plaid.](https://plaid.com/docs/transfer/index.html.md)

#### Investments Move 

[Get verified data for initiating an ACATS or ATON brokerage-to-brokerage transfer.](https://plaid.com/docs/investments-move/index.html.md)

#### Payments (Europe) 

[Make one-time payments, recurring payments, or payouts within your app.](https://plaid.com/docs/payment-initiation/index.html.md)

#### Financial Insights 

#### Transactions 

[Retrieve transaction data for budgeting tools, expense management, and more.](https://plaid.com/docs/transactions/index.html.md)

#### Investments 

[View holdings and transactions from investment accounts.](https://plaid.com/docs/investments/index.html.md)

#### Liabilities 

[Access loan data, like balances and interest rates, for student loans, mortgages, and credit cards.](https://plaid.com/docs/liabilities/index.html.md)

#### Enrich 

[Add detailed information and insights to your existing transactions data.](https://plaid.com/docs/enrich/index.html.md)

#### KYC, AML, and anti-fraud 

#### Identity Verification 

[Global KYC compliance and anti-fraud. Verify user identity data and documents.](https://plaid.com/docs/identity-verification/index.html.md)

#### Monitor 

[Use with Identity Verification to enable sanction, PEP, and watchlist screening for anti-money laundering compliance.](https://plaid.com/docs/monitor/index.html.md)

#### Beacon 

[Join the Plaid anti-fraud network](https://plaid.com/docs/beacon/index.html.md)

#### Protect 

[Prevent fraud before it happens — at every step of the user lifecycle.](https://plaid.com/docs/protect/index.html.md)

#### Instant Onboarding 

#### Layer 

[Onboard users instantly with just a phone number.](https://plaid.com/docs/layer/index.html.md)

#### Credit and Underwriting 

#### Consumer Report (by Plaid Check) 

[Make smarter credit and lending decisions with insights powered by Plaid Check.](https://plaid.com/docs/check/index.html.md)

#### Assets 

[Access users' financial information for loan underwriting.](https://plaid.com/docs/assets/index.html.md)

#### Statements 

[Get PDF statements directly from the user's bank, for underwriting verification and compliance.](https://plaid.com/docs/statements/index.html.md)

#### Income 

[Verify income and employment, for lending use cases and more.](https://plaid.com/docs/income/index.html.md)

---


# Authentication | Plaid Docs

Authentication 
===============

#### Building Plaid Core Exchange OpenID Connect Protocol 

#### Overview 

Core Exchange uses the [OpenID Connect protocol](https://openid.net/connect/) (OIDC) to authenticate your customers. OIDC is an extension of OAuth2. Plaid will use the OIDC flow to get authorization from the end user. This authorization allows Plaid to access your Core Exchange API on their behalf. In order to successfully allow your users to complete the authorization flow, you must:

*   [Create an OIDC-compliant server](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server)
*   [Issue Plaid a client ID and client secret](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#issue-plaid-a-client-id-and-client-secret)
*   [Guide your users through all the steps in the authorization flow](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#authorization-flow)

#### Create an OIDC-compliant server 

You can generate an OIDC-compliant server in any of the following ways:

*   Using your existing OAuth identity provider. (For example, Okta, Auth0, Ping Identity, Azure Active Directory, AWS Cognito)
    *   If you don't yet have an identity provider, Plaid recommends [our partner, Okta](https://www.okta.com/blog/2023/02/how-oktas-new-plaid-integration-keeps-your-banking-secure/) . Okta is an industry-leading, independent provider with expertise onboarding data partners to OAuth integrations. [Contact us](https://plaid.commailto:dataconnectivity@plaid.com) for help getting started with Okta.
*   Building a server with an [OIDC-certified open source or commercial implementation](https://openid.net/developers/certified/)
*   Building a server from scratch (not recommended)

##### Basic server requirements 

| Configuration | Notes |
| --- | --- |
| Server domain | Communicate the fully qualified domain name of your OIDC server to Plaid. |
| Well-known configuration endpoint | Your organization must respond to Plaid's request with the information listed in the next section . |

##### Well-known configuration 

The `/.well-known/openid-configuration` endpoint of the OIDC server is a public endpoint that accepts HTTP GET requests without authentication. It returns a JSON object containing the minimum following values:

| Property | Description |
| --- | --- |
| `authorization_endpoint` | The authorization endpoint: the endpoint hosting the user authentication page. Must support TLS and be publicly accessible. |
| `token_endpoint` | The endpoint Plaid will call to exchange the authorization code for an access token. |
| `userinfo_endpoint` | The endpoint Plaid will call to retrieve the user identifier. |
| `token_endpoint_auth_methods_supported` | The supported authentication methods Plaid can use to [request an access token](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#4-plaid-requests-an-access-token) from the `token_endpoint`.  
  
(If omitted, Plaid will use [basic authentication](https://www.rfc-editor.org/rfc/rfc6749#section-2.3.1) by default.) |
| `response_types_supported` | An array of supported response types. Plaid expects this to include `code`. |
| `scopes_supported` | Transaction data subscriptions |

###### Example 

**Plaid's request:**

```bash
curl -X GET 'https://auth.firstplatypusbank.com/.well-known/openid-configuration'
```

**Your response:**

```json
{
  "authorization_endpoint": "https://auth.firstplatypusbank.com/oauth2/v1/authorize",
  "token_endpoint": "https://auth.firstplatypusbank.com/oauth2/v1/token",
  "userinfo_endpoint": "https://auth.firstplatypusbank.com/oauth2/v1/userinfo",
  "token_endpoint_auth_methods_supported": ["client_secret_basic"],
  "response_types_supported": ["code"],
  "scopes_supported": ["openid", "offline_access"]
}
```

#### Issue Plaid a client ID and client secret 

In order to allow Plaid to authenticate its request for an access token, you must issue Plaid a client ID and client secret. These allow Plaid to identify itself. You may create the client ID and client secret using your preferred method, but we provide some guidance in the sections below.

##### Client ID 

A client ID is a public identifier that you assign to Plaid. While it is not secret, we recommend choosing a client ID that is not easy to guess.

**Note:** The client ID must be between 8 and 256 characters long.

###### How to create a client ID 

One way to create a client ID is to use a random 32-character hex string. For example:

```javascript
import crypto from "crypto";
const randomString = crypto.randomBytes(16).toString("hex");
console.log(randomString)
```

##### Client secret 

The client secret is essentially a password that you assign to Plaid. In order to keep it secure, please follow these [best practices](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) :

*   Generate the client secret in a way that makes it impossible to guess or backwards-generate. (For example, do not use a UUID as many common libraries take into account the timestamp or MAC address of the generating server.)
*   Never store the client secret in plain text—always keep it encrypted or hashed.
*   Make the client secret visually different from the client ID. (This reduces the risk of a user copy/paste error when handling the client ID and client secret.)

**Note:** The client secret must be between 8 and 256 characters long.

###### How to generate a client secret 

One way to securely generate a client secret is to follow the steps below:

1.  Create a 256-bit value using a cryptographically secure pseudo random number generator (CSPRNG)
2.  Convert the value from step 1 to a hexadecimal representation

**Example:**

```javascript
import crypto from "crypto";
const randomString = crypto.randomBytes(32).toString("hex");
console.log(randomString)
```

#### Authorization flow 

Once you have an OIDC-compliant server and have issued Plaid a client ID and client secret, you are ready to complete the authorization flow. The flow described below conforms to commonly implemented patterns for the [OIDC spec](https://openid.net/specs/) . Plaid welcomes partner [feedback](https://plaid.commailto:dataconnectivity@plaid.com) .

**Steps overview:**

1.  [Plaid redirects the end user to your authorization endpoint](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#1-plaid-redirects-the-end-user)
2.  [The user completes all authentication steps](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#2-the-user-completes-all-authentication-steps)
3.  [You create an authorization code and send it to Plaid](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#3-you-give-plaid-an-authorization-code)
4.  [Plaid requests an access token](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#4-plaid-requests-an-access-token)
5.  Plaid uses the access token to identify the user and authenticate Plaid's requests to your [Core Exchange API](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/index.html.md)

##### Steps 

###### 1\. Plaid redirects the end user 

When your user first starts the process of linking their account, Plaid redirects their browser to the authorization endpoint specified in your [well-known configuration](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#well-known-configuration) . Plaid's redirect includes the following query parameters:

| Query parameter | Description | Value |
| --- | --- | --- |
| `response_type` | A string, indicating type of response Plaid expects. | Set to: `code` |
| `redirect_uri` | Where Plaid expects your organization to redirect back to once the user completed all authentication steps. | https://cdn.plaid.com/link/v2/stable/oauth.html |
| `scope` | A set of strings indicating the set of scopes Plaid requests access to. | Will be set to `openid` and `offline_access`, at minimum |
| `client_id` | The [client ID](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#issue-plaid-a-client-id-and-client-secret) you issued to Plaid. | A [client ID](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#client-id) |
| `state` | Your organization will return the same string when redirecting to the `redirect_uri`. | An opaque string |
| `prompt` | Specifies the type of authentication prompt the server will send to the end user. | Set to `login` |
| `code_challenge` | _Optional:_ This value will be included only if your organization is using PKCE. | The `code_verifier`, either as a Base64URL-encoded hash or in plain text |
| `code_challenge_method` | _Optional:_ This value will be included only if your organization is using PKCE. | plain: The code\_verifier is in plain text |

**Plaid redirect example:**

```json
https://auth.firstplatypus.com/oauth2/v1/authorize?response_type=code
&client_id=dc1fe34ae9e5e98147f2fd76060016a4
&redirect_uri=https%3A%2F%2Fcdn.plaid.com%2Flink%2Fv2%2Fstable%2Foauth.html
&state=v2.9f77edf0-a328-4501-9528-4a5f460cf770.0.0
&scope=openid%20offline_access%20accounts%20transactions
&prompt=login
&code_challenge=4dKRcTlKg7PbBxYokEH5gbfwfXcUdvDVYVdFZniVq4s
&code_challenge_method=S256
```

This page will be requested directly by the user's device.

##### 2\. The user completes all authentication steps 

Control of user authentication has now been handed off to you. A typical authentication flow will include a username and password submission form and a 2FA step. For partners with native mobile applications, Plaid strongly recommends enabling support for [App2App](https://plaid.comhttps://plaid.com/core-exchange/docs/user-experience/index.html.md#app2app) and using [biometric authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/user-experience/index.html.md#webauthn) to improve the user's authentication experience.

**Note:** If a user does not complete all the required steps (for example, if they choose to cancel rather than authorize) you should [handle it as an error](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#user-cancellation) .

##### 3\. You give Plaid an authorization code 

After the user completes all required authentication steps, your organization generates a temporary authorization code and redirects the user's browser back to the `redirect_uri`. The following query parameters must be included with the request:

| Query parameter | Description |
| --- | --- |
| `code` | The temporary authorization code. Plaid will exchange this for an access token in the [next step](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#4-plaid-requests-an-access-token) . |
| `state` | The `state` parameter from the [step 1](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#1-plaid-redirects-the-end-user) . Plaid verifies that the two values match. |

**Example of your response:**

```json
https://cdn.plaid.com/link/v2/stable/oauth.html?code=1284918391
&state=eyJvYXV0aF9zdGF0ZV
```

##### 4\. Plaid requests an access token 

Plaid sends a request to your `token_endpoint`. Unlike the previous steps, the request to the `token_endpoint` is a backend-to-backend call and must be authenticated. The authentication credentials consist of the [client ID and client secret](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#issue-plaid-a-client-id-and-client-secret) you issued to Plaid. The authentication method will be one of the [authentication methods](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) specified in your [well-known configuration](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#well-known-configuration) . For example, if the authentication method is set to `client_secret_basic`, Plaid will include a [basic authentication](https://plaid.comhttps://www.twilio.com/docs/glossary/what-is-basic-authentication/index.html.md) header in its request.

Plaid will send the parameters listed in the table below in the body of the request, in `application/x-www-form-urlencoded` format.

###### Body parameters 

| Body parameter | Description | Value |
| --- | --- | --- |
| `prompt` | Specifies the type of a prompt the server will send to the end user. | Will be set to: `consent` |
| `grant_type` | The type of grant Plaid is exchanging for an access token. (In this case, an authorization code.) | Will be set to: `authorization_code` |
| `code` | The temporary authorization code Plaid is exchanging for the access token. | The `code` you sent to Plaid in the [previous step](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#3-you-give-plaid-an-authorization-code) |
| `redirect_uri` | Where Plaid expects your organization to redirect back to once the user completed all authentication steps. | `https://cdn.plaid.com/link/v2/stable/oauth.html` |
| `scope` | The set of possible scopes. | An array of scopes, for example: `[offline_access, openid, accounts, transactions, identity]` |
| `audience` | _Optional:_ Defines who the token is for. This value will be sent if Plaid has this information. [More information](https://community.auth0.com/t/what-is-the-audience/71414) | A string, for example: `https://test-api` |
| `code_verifier` | _Optional:_ This value will be included only if your organization is using PKCE. | The `code_verifier`, created prior to starting the authentication flow |

**Plaid request example:**

```bash
curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs"
--data-raw '{
    "prompt": "login",
    "grant_type": "authorization_code",
    "code": "1284918391",
    "redirect_uri": "https://cdn.plaid.com/link/v2/stable/oauth.html",
    "scope": ["offline_access", "accounts"]
}'
```

Your organization validates that the `client_id`, `client_secret`, `code` and `redirect_uri` all match the expected values. If everything is correct, you respond to Plaid with the `access_token`, `id_token`, and `refresh_token`. Plaid requires all of these values to later access your Core Exchange API.

###### Response parameters 

| Property | Description |
| --- | --- |
| `access_token` | An opaque string (likely a JWT structured according to the [Oauth2 specification](https://datatracker.ietf.org/doc/html/rfc9068#section-2.2) ). Plaid will present this string as a bearer token to all requests made to your Core Exchange API. This encodes the identity of the user and the scope of access granted. |
| `expires_in` | The lifetime of the access token, in seconds. Typically 15 minutes (900 seconds). Plaid checks for expiration before using an access token. If the access token is expired, Plaid will use the refresh token to request a new access token. If your organization expires the token before the stated expiration date, Plaid expects to receive a 401 response with an error code of "602 not authorized". |
| `id_token` | An [OIDC ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . Plaid only reads the `sub` field from this token.  
In a deployment with multiple financial institutions, the `sub` field must be unique to each financial institution. (It doesn't need to be unique to the user across all financial institutions.) |
| `refresh_token` | An opaque string (likely a JWT) that can be used to request a new access token. Plaid will use this to fetch data periodically long after the original access token expires. See the [refresh flow](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#refresh-flow) section for more information.  
Plaid doesn't recommend setting an inactivity timeout for the refresh token because it's not a good indicator of whether a user is active with a Plaid partner. For example, some Plaid partners can trigger Plaid to call the Core Exchange endpoint `/accounts/{accountID}` infrequently for large transactions. |

**Example of your response:**

```json
{
  "access_token": "agstynmdygjdghabrgraeh...",
  "expires_in": 900,
  "id_token": "snsyjrhvjdtvyjvsgcegaethstj...",
  "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}
```

After it receives this response, Plaid has everything it needs to access your Core Exchange API.

##### Error handling 

If an error occurs during the [authorization flow](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#authorization-flow) , respond with the appropriate [error](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#errors) . (See [RFC 6749 section 4.1](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1) for a full description of each error.)

###### Incorrect redirect URI 

If the request fails due to an incorrect, missing, invalid, or mismatched `redirect_uri`, notify Plaid of the error and _do not_ redirect the user to the `redirect_uri`. We recommend displaying an error page to notify the user that an error has occurred.

###### Expired access token 

If Plaid sends an expired `access_token` for any reason, send a 401 response with an error code of "602 not authorized".

###### User cancellation 

If the user cancels the request or if the request fails for any other reason other than an incorrect URI, include the following required query parameters with the request.

  

| Query parameter | Description |
| --- | --- |
| `error` | The reason for the error. See the [Errors](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#errors) table below for a list of possible errors. |
| `state` | The opaque string Plaid passed as the `state` parameter in the [authorization\_endpoint](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#1-plaid-redirects-the-end-user) redirect step. |

**Example error response:**

```json
https://cdn.plaid.com/link/v2/stable/oauth.html?error=access_denied
&state=eyJvYXV0aF9zdGF0ZV
```

###### Errors 

  

| Error value | Description |
| --- | --- |
| `invalid_request` | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
| `unauthorized_client` | The client is not authorized to request an authorization code using this method. |
| `access_denied` | The resource owner or authorization server denied the request. |
| `unsupported_response_type` | The authorization server does not support obtaining an authorization code using this method. |
| `invalid_scope` | The requested scope is invalid, unknown, or malformed. |
| `server_error` | The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.) |
| `temporarily_unavailable` | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code can't be returned to the client via an HTTP redirect.) |

#### Refresh flow 

For some use cases, Plaid needs to periodically fetch fresh data on behalf of the user. To get a new access token, Plaid makes another request to your `token_endpoint` with a different set of parameters. The request body will be encoded in the `application/x-www-form-urlencoded` format.

###### Body parameters 

| Body parameter | Description | Value |
| --- | --- | --- |
| `grant_type` | Specifies that Plaid is requesting a new access token to replace the expired access token. | Will be set to: `refresh_token` |
| `refresh_token` | The refresh token you issued to Plaid.  
  
Plaid recommends setting the expiration at 13 months. This allows you to avoid running into expiration issues during time-sensitive intervals (for example, on tax day). | Example: `dhcsrtjsrgayvkdisfdgntshstu...` |

**Plaid request example:**

```bash
curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs"
--data-raw '{
    "grant_type": "refresh_token",
    "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}'
```

Your organization validates that the `grant_type` and `refresh_token` are valid and responds with the `access_token`, and `id_token`. Plaid will use these values to continue to access your Core Exchange API.

###### Response parameters 

| Property | Description |
| --- | --- |
| `access_token` | An opaque string (likely a JWT structured according to the [Oauth2 specification](https://datatracker.ietf.org/doc/html/rfc9068#section-2.2) ). Plaid will present this string as a bearer token to all requests made to your Core Exchange API. This encodes the identity of the user and the scope of access granted. |
| `expires_in` | The lifetime of the access token, in seconds. Typically 15 minutes (900 seconds). Plaid checks for expiration before using an access token. If the access token is expired, Plaid will use the refresh token to request a new access token. If your organization expires the token before the stated expiration date, Plaid expects to receive a 401 response with an error code of "602 not authorized". |
| `id_token` | An [OIDC ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . Plaid only reads the `sub` field from this token.  
In a deployment with multiple financial institutions, the `sub` field must be unique to each financial institution. (It doesn't need to be unique to the user across all financial institutions.) |

**Example success response:**

```json
{
  "access_token": "lngarogglkcangasgabba...",
  "expires_in": 900,
  "id_token": "snsyjrhvjdtvyjvsgcegaethstj..."
}
```

##### Error handling 

If an error occurs during the [refresh flow](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#refresh-flow) , respond with a 400 HTTP status code. You must include the appropriate `error` as shown in the [table below](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#error-codes) . You may optionally include an error description and an error URI. (See [RFC 6749 section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) for complete information of each field.)

**Example error response:**

```json
{
  "error": "invalid_grant",
  "error_description": "Authorization grant does not match redirect URI",
  "error_uri": "https://www.your-org.com/human-readable-error-info/"
}
```

  

###### Error codes 

| Error code | Description |
| --- | --- |
| `invalid_request` | The request is missing a required parameter. |
| `invalid_client` | Client authentication failed. |
| `invalid_grant` | The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client (rely on error description from FIs to further break this out). |
| `unauthorized_client` | The authenticated client is not authorized to use this authorization grant type. |
| `unsupported_grant_type` | The authorization grant type is not supported by the authorization server. |
| `invalid_scope` | The requested scope is invalid, unknown, or malformed. |

#### App2app 

App2app is a feature that allows mobile apps using OAuth2 or OpenID Connect based authentication to offer a simpler, faster flow. App2app can be used if the user already has an app provided by the authorization server owner installed on their mobile device.

To implement App2app with your Core Exchange API:

###### 1\. Set up app deep link URLs 

Set up claimed HTTPS URLs so that the OAuth redirect launches the app (if installed) instead of the mobile web page. Ensure fallback to web if the app is not installed or is unavailable. (For example, if the user is on a desktop.)

See the resources below for instructions on how to set up deep link URLs:

*   iOS: [Universal links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content?language=objc)
*   Android: [App Links](https://developer.android.com/training/app-links#android-app-links)

###### 2\. Set up in-app flow to issue OAuth authorization code 

*   **Native experience** (Recommended): Build a fully in-app flow whereby the users completes the authentication flow and the authorization code is issued from within the app, before redirecting back to Plaid.
*   **Semi-native experience** (Alternative): If a fully native experience cannot be resourced we can discuss alternative options, but there will be UX trade-offs.

###### 3\. Provide the authorization endpoint redirect URLs to Plaid 

Plaid recommends that the data partner provides Plaid with two redirect URLs:

*   An App2app flow redirect URL
*   A regular web-based flow redirect URL

This allows Plaid to control the user path and isolate any issues that may arise. (For example, if a specific developer ("app") incorrectly implements the App2app flow.)

---


# Changelog | Plaid Docs

Plaid Core Exchange Changelog 
==============================

#### Tracks changes to Plaid Core Exchange 

See the following changelist for updates to the Core Exchange specification. Core Exchange uses the same version numbers as FDX.

\=\*=\*=\*=

#### v6.3 Core Exchange API specification  

##### New Features 

**Enhanced Pagination**: Added `pageKey` query parameter and `nextPageKey` response property for improved pagination across all paginated endpoints:

*   `GET /accounts`
*   `GET /accounts/{accountId}/payment-networks`
*   `GET /accounts/{accountId}/statements`
*   `GET /accounts/{accountId}/transactions`

**New Deposit Account Types**: Added support for specialized savings accounts:

*   `FIRSTHOMESAVINGSACCOUNT` - First Home Savings Account type
*   `HIGHINTERESTSAVINGSACCOUNT` - High Interest Savings Account type

**Enhanced Contact Information**: Improved contact data support with new fields:

*   **Account Holder Relationships**: Added `AUTHORIZED_SIGNER` relationship type for account holders
*   **Phone Number Enhancements**:
    *   New phone types: `BOTH`, `PERSONAL`
    *   Added `network` property for mobile network information
    *   Added `primary` property to identify primary contact numbers
    *   Enhanced country code validation with new pattern `^\\+?[1-9][0-9]{0,2}$`

**Enhanced Loan Account Details**: Added optional properties for loan accounts:

*   `currentSchool` - Current educational institution for student loans
*   `loanProviderName` - Name of the loan provider

**Transaction Enhancements**:

*   Added `cardNumberDisplay` property for all transaction types to show masked card numbers
*   Added date filtering with `startDate` and `endDate` query parameters for statements and transactions endpoints

##### Breaking Changes 

**Contact Phone Number Field Changes**:

*   Increased maximum length for `telephones[].country` from 3 to 4 characters
*   Modified `payee` field structure in deposit transactions (removed maxLength constraint and changed type structure)

**Schema Cleanup**: Removed unused `TelephoneNumberType` schema

\=\*=\*=\*=

#### v6.2 Core Exchange API specification  

##### New Features 

*   **Digital Wallet Support**: Added support for `DIGITAL_WALLET` account category across all account types and transactions
*   **New Currency Support**: Added support for `ZWG` (Zimbabwean Gold) currency code across all account types, transactions, and investment holdings
*   **Investment Account Enhancement**: Added `PREPAID` account type for investment accounts
*   **Digital Wallet Account Descriptor**: New `DigitalWalletDescriptor` schema added to the `/accounts` endpoint response

##### Breaking Changes 

**Pagination Changes**: Removed optional `totalElements` property from paginated responses in the following endpoints:

*   `GET /accounts`
*   `GET /accounts/{accountId}/payment-networks`
*   `GET /accounts/{accountId}/statements`
*   `GET /accounts/{accountId}/transactions`

**Statement Status Cleanup**: Removed the following enum values from statement status:

*   `AVAILABLE`
*   `FAILED`
*   `PROCESSING`

\=\*=\*=\*=

#### v6.1 Core Exchange API specification  

##### FDX changelist 

*   Minor updates and improvements to existing schemas

##### Plaid changelist 

*   Internal improvements and optimizations

\=\*=\*=\*=

#### v6.0 Core Exchange API specification  

##### FDX changelist 

`US_FEDNOW` (Federal Reserve Instant Payment System) is now an accepted `PaymentNetworkType` in the `/payment-networks` endpoint

###### Breaking changes 

*   In the response for the `/accounts/{accountId}` endpoint, the account object is no longer wrapped with a named property (ex. `depositAccount`). The discriminator value `accountCategory` is now required on each account type.

The `accountCategory` may be any of the following:

*   `ANNUITY_ACCOUNT`
*   `COMMERCIAL_ACCOUNT`
*   `DEPOSIT_ACCOUNT`
*   `INSURANCE_ACCOUNT`
*   `INVESTMENT_ACCOUNT`
*   `LOAN_ACCOUNT`
*   `LOC_ACCOUNT`

(These values have not changed since prior versions v5.2 and v5.3.)

*   In the response for the `/accounts/{accountId}/transactions` endpoint, the transaction object is no longer wrapped with a named property (ex. `depositTransaction`). The discriminator value `accountCategory` is now required on each transaction object.

An implementer’s mapping of each transaction must set the required the `accountCategory` property.

The `accountCategory` may be any of the following:

*   `DEPOSIT_ACCOUNT`
    
*   `INVESTMENT_ACCOUNT`
    
*   `LOAN_ACCOUNT`
    
*   `LOC_ACCOUNT`
    
*   The `holding` object in investment accounts now supports an array of `securityIds` with `id`/`idType` pairs. (These pairs have replaced the `securityId`/`securityIdType` keys as identifiers.)
    

##### Plaid changelist 

###### Breaking changes 

In AccountWithDetails (response for `/accounts/{accountId}` endpoint) removing the seven `xxxAccount` properties and requiring discriminator value `accountCategory`: on each account type, one of `ANNUITY_ACCOUNT`, `COMMERCIAL_ACCOUNT`, `DEPOSIT_ACCOUNT`, `INSURANCE_ACCOUNT`, `INVESTMENT_ACCOUNT`, `LOAN_ACCOUNT` or `LOC_ACCOUNT`. These values have not changed since prior versions v5.2 and v5.3

An implementer’s mapping of each account must set the required `accountCategory` property. The account object is no longer wrapped with a named property (ex. `depositAccount`).

\=\*=\*=\*=

#### V5.3 Core Exchange API specification  

##### FDX changelist 

*   A new account type (`CommercialAccountType`) was added. The following account types are classified as commercial accounts:
    *   `COMMERCIALDEPOSIT`
    *   `COMMERCIALINVESTMENT`
    *   `COMMERCIALLOAN`
    *   `COMMERCIALLINEOFCREDIT`
*   Commercial account type includes a new descriptor: `CommercialAccountDescriptor`.

###### Breaking changes 

*   The ISO 3166 country code standard was updated to ISO 3166-1 alpha-2.
*   The list of ISO 4217 currency codes was updated. (As of January 1, 2023)
*   **Note:** Some country codes (`AN`, `CS`) and currency codes (`HRK`) were removed in the updated version, making this a breaking change. (Please see the [ISO standards](https://www.iso.org/standards.html) for more information.)

##### Plaid changelist 

###### Breaking changes 

*   Plaid will not provide balance product support for the new `CommercialAccountType`.

\=\*=\*=\*=

#### V5.2 Core Exchange API specification  

##### FDX changelist 

*   None

##### Plaid changelist 

*   None

\=\*=\*=\*=

#### V5.1 Core Exchange API specification  

##### FDX changelist 

*   For the endpoints that Plaid supports, FDX introduces minor enum, model, and formatting changes in this version.

###### Breaking changes: 

*   None

##### Plaid changelist 

*   Plaid introduces support and documentation for FDX Digital Assets.

\=\*=\*=\*=

#### V5.0 Core Exchange API specification  

##### FDX changelist 

*   For the endpoints that Plaid supports, FDX introduces minor enum, model, and formatting changes in this version.

###### Breaking changes: 

*   The `state` property on an Address was renamed to the more inclusive `region`.
*   The specification requires timestamps on transactions be in ISO 8601 format.

##### Plaid changelist 

*   Plaid introduces support and documentation for FDX investment models, including investment accounts, investment holdings, and investment transactions.

\=\*=\*=\*=

#### v4.6  

##### FDX changelist 

*   None

##### Plaid changelist 

*   Plaid introduces Core Exchange in this version by choosing a subset of FDX endpoints to support and adding Plaid-specific documentation.

---


# Dashboard overview | Plaid Docs

Dashboard overview 
===================

#### An overview of the configuration options available in Plaid's Dashboard 

### Overview 

After completing signup, you’ll land on the Overview page in the Open Finance section in the navigation. This page will get you started on your journey to build your FDX-aligned API and launch your institution on Plaid’s network.

#### Integration Health 

Integration Health provides real-time error logs and health metrics for your Plaid integration. You can search and filter error logs to investigate and troubleshoot issues your customers are experiencing.

##### Metrics and Terminology 

**Error**: A request is classified as an error if Plaid encounters an error anywhere during account linking or data extraction while interacting with your API. Though errors often result from non-200 HTTP responses from your API, successful 200 requests to your API can be marked as errors.

**Success**: A request is classified as a success if Plaid does not encounter any errors during account linking or data extraction while interacting with your API.

**Health**: This metric represents the proportion of successful API calls relative to the total API calls made across your API's data resource endpoints. It is calculated as: **(Number of successful API calls) / (Total API calls made)**

(An image of "Overview")

**Overview**

(An image of "Detailed logs")

**Detailed logs**

### Core Exchange 

The Core Exchange section allows you to configure your institution, which involves configuring Plaid’s access to your API and also setting up your institution’s brand in Plaid Link.

##### 1\. Configure Plaid’s access to your FDX API 

There are three different institution configuration profiles that are available to you. Development and Staging can be configured to pre-production environments allowing you to test them via Validator. The Production configuration profile is designated only for your production environment.

(An image of "Configuration")

##### 2\. Configure your institution’s brand info 

Using the Brand Editor you can configure your logo, institution name, and institution URL.

(An image of "Brand editor")

##### For Digital Banking Platforms 

If you are a Digital Banking Platform, then your Core Exchange section will have a slightly different view to support the many institutions that you might support as your customers.

(An image of "View for digital banking platforms")

### Permissions Manager 

The Permissions Manager section allows you to:

*   Search by customer to view authorization details of their connections
*   View detailed API docs
*   Set up webhooks to get real-time alerts each time a customer connects to or revokes access from a new application

(An image of "Permissions manager")

**Lookup**

(An image of "API docs")

**API docs**

(An image of "Webhooks")

**Webhook configuration**

### App Directory 

The App Directory section displays details about the apps your customers are connected to, including categories and number of connections. You can also view docs for App Directory’s FDX-aligned API.

(An image of "App directory")

---


# Implementation Checklist | Plaid Docs

Implementation Checklist 
=========================

#### Checklist for implementing Plaid Core Exchange 

#### Scoping and implementation 

*    Review the [Core Exchange API Reference documentation](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/index.html.md)
*    Review the [architecture diagram](https://plaid.comhttps://plaid.com/core-exchange/docs/implementation-checklist/index.html.md#architecture-diagram)
*    Try out our [Postman collection](https://plaid.comhttps://plaid.com/core-exchange/docs/mock-server/index.html.md) to test requests and responses on a mock bank server
*    Complete the [Intake Questionnaire](https://forms.gle/SSJAfnrxLv7b1Em99) . The information provided allows us to best support you through your onboarding experience
*    Get access to the Plaid Data Partner Dashboard:
    *   Your Plaid contact will provide you a one-time use link to either sign up for a data partner dashboard account if you do not already have Plaid dashboard access or create a new team if you already have access to the dashboard as a Plaid customer.
 Gather business information

In our onboarding flow, we verify your organization and require the following information which you can collect in advance:

*   Name and business email address of a responsible business contact representing the data provider organization
*   Company address
*   Company name
*   Company tax ID
*   Company [Legal Entity Identifier](https://www.gleif.org/en/about-lei/get-an-lei-find-lei-issuing-organizations)
*   Industry
*   Licensing and registration (e.g., FDIC, NCUA, SIPC)

*    Gather technical contact information
    Before you go live, we require technical contact information In the event an urgent technical issue arises:
    
    *   Shared email address
    *   Phone number (if available)
    *   Additional individual contacts
    
*    Prepare one or more test accounts for each type of account you support (checking, savings, credit card, loan, 401k, etc.) Ensure that:

*    All accounts have balance data
*    All accounts have contact data
*    Depository, loan, and investment accounts have transaction data
*    Depository accounts have payment networks data

*    Allowlist the following Plaid IPs:

*    18.214.218.91
*    3.211.30.208
*    3.214.25.67
*    54.88.74.128
*    54.208.59.10
*    54.88.202.28
*    34.199.37.46
*    35.168.137.48
*    3.215.49.214
*    34.202.178.138
*    52.0.205.192
*    52.3.166.211
*    35.174.147.86
*    52.88.82.239
*    52.41.247.19
*    3.233.249.56
*    35.153.85.253
*    3.219.116.195

#### Building and testing 

##### Develop and test authentication 

*    Create an [OIDC-compliant server](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) , including:

*    A server domain
*    A [well-known configuration endpoint](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#well-known-configuration)

*    Issue Plaid a [client ID and client secret](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#issue-plaid-a-client-id-and-client-secret)
*    Make identity information available to Plaid (Choose one below):

*    OIDC-compliant:

*    [ID Token + JWKS URI Route](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)
*    [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)

*    Non-OIDC compliant (not recommended):

*    [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#customerscurrent) endpoint

*    Create a [token exchange](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#4-plaid-requests-an-access-token) endpoint

##### Develop and test FDX data subsets 

*    [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts) : Search and view customer accounts
*    [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccoutid) : Get account balances, liabilities, and other information
*    [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsacouuntidpayment-networks) : Get payment networks supported by an account
*    [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#) : Get account contact information
*    [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#) : List all account transactions
*    [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#customerscurrent) (only if OpenID Connect compliance is not followed): Get the ID of the customer within the authorization scope

#### Go-live 

##### Get ready for production 

*    Confirm you have implemented strong authentication in your OAuth flow (i.e., MFA)
*    Confirm your organization's name, logo, and URL. Plaid uses this information to populate your organization's details in Plaid Link. Your logo file must be a 96x96 or 152x152 circular PNG and under 2MB
*    If you would like to make an external launch announcement, reach out to our Plaid team to finalize plans
*    Once you have validated your integration, request production access in the [Plaid dashboard](https://dashboard.plaid.com/) or reach out to your Plaid contact

##### Pilot and migrate 

_(Note: This section only applies to existing Plaid partners)_

If your institution is already supported in [Plaid Link](https://plaid.comhttps://plaid.com/core-exchange/docs/user-experience/index.html.md) or you are a [platform provider](https://plaid.comhttps://plaid.com/core-exchange/docs/implementation-checklist/index.html.md#key-considerations-for-digital-banking-platforms) with numerous institutions, we will partner together to develop a pilot and migration plan. Migrations typically have 4 phases:

  

|  | Phase | Description | Timeline\* |
| --- | --- | --- | --- |
| 1 | Friends and Family Testing | Limited access, internal user traffic | ~ 2 weeks |
| 2 | Pilot Cohort | Enable new connections in production for pilot cohort, monitor health and resolve issues | ~ 2 weeks |
| 3 | Remaining Cohorts | Enable new connections for remaining cohorts _in production, monitor health and resolve issues  
  
\*\*# of cohorts is partner dependent_ | ~ 2-3 weeks |
| 4 | Existing User Migration | After integration health is validated, Plaid will begin a process to migrate all existing items over to the OAuth + API connection. | ~120 days |

_\*Timeline illustrative. Speed contingent on ability to validate institutional health, address any open issues etc._

#### Ongoing management 

We will continue to partner together to ensure integration quality after you go live on API connectivity with Plaid. Key integration health metrics Plaid monitors include: conversion, data access success rate, data availability and accuracy.

*    Update the Plaid team with the correct point of contact to support ongoing integration health
*    Log the identifiers below to aid in troubleshooting issues with Plaid:

*   OAuth state parameter:

*   Plaid sends a unique string in the state parameter when redirecting the user’s browser to the `authorization_endpoint`. Useful in debugging OAuth flow errors.

*   X-Request-ID

*   Plaid sends this header in requests to your resource server. It can be correlated with error logs on our [Integration Health dashboard](https://plaid.comhttps://plaid.com/core-exchange/docs/dashboard-overview/index.html.md#overview) .

*   User identifier

*   This is useful in debugging the request flow for a given user.
*   Depending on how you set up your API this value can be from the following sources:

*   The value of `sub` from your OIDC token
*   The value of `sub` from your OIDC `userinfo_endpoint`
*   Value of `customerId` from the `/customers/current` endpoint

*    Consider ways to take your integration to the next level:

*    Increase consumer throughput with [App2App functionality](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#app2app)
*    Show your customers their most up-to-date connections to Plaid-powered apps and enable them to make updates in real-time, automatically syncing permissions across the financial ecosystem via [Permissions Manager](https://plaid.com/privacy-controls-permissions-manager/)

#### Key considerations for Digital Banking Platforms 

Partnering with Digital Banking Platforms is essential to how Plaid leads the market in preparing for the open finance future. Over 30 platforms, representing 7000+ financial institutions are already live or in the process of going live with API-based data connectivity with Plaid.

The Plaid team has made key investments to support rapid scaling of our API migrations. Our Data Partner Dashboard and internal tooling make it straightforward to migrate hundreds of financial institutions and millions of new and existing users to API in a matter of weeks.

##### 1\. Execute an “opt-out migration” 

Financial institutions and their end users now expect highly reliable and secure data access. In order to deliver that experience as quickly as possible, we recommend an "opt-out" migration strategy for Digital Banking Platform institutions.

###### How to execute: 

*    Communicate with your financial institutions that Plaid API access is rolling out for all institutions
*    Share with Plaid the number of institutions you support
*    Determine if cohort-based ramping of institutions is needed (details to consider in [step 2](https://plaid.comhttps://plaid.com/core-exchange/docs/implementation-checklist/index.html.md#step-2-consider-complexities) )
*    Dependent on the scale of your existing Plaid volume, we may encourage either:

*    **Friends and family pilot**: Set up 1-2 financial institutions for testing in production under a pseudonym only findable by active testers. Plaid will share a PDF checklist of tests to run to testers.
*    **Production pilot**: Bring 1-5 financial institutions live in production to validate integration before bringing the rest of your institutions live.

*    Upload financial institutions into the [Data Partner dashboard](https://dashboard.plaid.com/)
*    Plaid brings financial institutions live on API!

##### 2\. Consider backend data complexities upfront: 

*    **Pilot/testing plan**: Do you have different backend pods, product lines, or backend core groupings that might align to different backend data models? If so, we encourage representing each subgroup in a pilot cohort to uncover any variability or errors.
*    **Account and routing numbers**: There is zero room for error when it comes to accuracy of account and routing numbers. We have found with platforms representing different backend cores there can be some edge-case discrepancy. Please validate that \`/payment-network\` data is accurate for all institutions before going live.

#### Architecture diagram 

This sequence diagram depicts the standard flow of an end-user selecting an institution in Plaid Link and the resulting interaction flow between Plaid and a data partner’s API. Core Exchange offers flexibility that meets your needs, so exact flows can vary depending on your OAuth 2.0 and FDX implementation.

(An image of "core-exchange-sequence-diagram")

---


# Home - Welcome | Plaid Docs

Welcome 
========

#### Plaid Developer Docs for an FDX-Aligned API 

#### Introduction 

With Plaid’s Developer Docs for an FDX-aligned API, we’ve taken the guesswork out of building to the FDX standard. With our simplified spec, your organization will know exactly which fields are needed to power connectivity to the Plaid Network in alignment with FDX. With our implementation guide, you’ll enable your customers to seamlessly connect their accounts to the thousands of applications within the Plaid network (the largest of any aggregator), including payment services, budgeting apps, and more. Plaid’s open finance solutions are completely free for data providers and makes it easier for you to comply with the key aspects of open banking regulation. It includes three parts:

**1\. Core Exchange:** Offers an easier way to implement an FDX-aligned API in a matter of weeks, with these docs, developer tooling in our data partner dashboard, and dedicated support from our expert team.

Once your API is in place, we have additional solutions to give you visibility into consumer and app-level connections as well as comply more easily with 1033 standards.

**2\. Permissions Manager:** Gives data providers the tools to gain visibility into the authorization details for connections their customers have made via Plaid, build a consent portal that enables customers to manage their connections, and receive real-time alerts. Available via no-code dashboard as well as APIs and webhooks.

**3\. App Directory:** Gives data providers insights about the thousands of apps on Plaid’s network that their customers have connected to, including categories and number of connections. FDX-aligned and available via no-code dashboard as well as APIs.

#### CFPB’s rulemaking on Personal Financial Data rights (i.e. “1033”) 

The Consumer Financial Protection Bureau (CFPB) [finalized its Section 1033 rule](https://www.consumerfinance.gov/about-us/newsroom/cfpb-finalizes-personal-financial-data-rights-rule-to-boost-competition-protect-privacy-and-give-families-more-choice-in-financial-services/) on October 22, 2024. This rule has formalized the requirement for certain providers of financial services to provide a developer interface (an API) to allow their customers to access and share their financial data. Learn more about the Dodd-Frank Section 1033 rule and key considerations for financial services providers going forward in this article.

Building your FDX-aligned API with Plaid will help prepare your organization to comply with upcoming regulatory requirements. For more information on preparing your open banking API strategy, please reach out to us [here](https://plaid.com/products/core-exchange/#contactForm) .

#### What this guide contains 

This documentation contains all the information you need to build your own FDX-aligned API. It includes:

*   A [checklist](https://plaid.comhttps://plaid.com/core-exchange/docs/implementation-checklist/index.html.md) of all the steps that must be completed during each stage of development
*   A visual walkthrough of the [experience](https://plaid.comhttps://plaid.com/core-exchange/docs/user-experience/index.html.md) your customers will have once Plaid is fully integrated to your FDX-aligned API
*   An in-depth explanation of the [OpenID Connect-compliant authentication process](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md)
*   Example requests you can send to our [mock server](https://plaid.comhttps://plaid.com/core-exchange/docs/mock-server/index.html.md) to get familiar with FDX data payloads
*   An [API reference](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/index.html.md) with sample requests, responses, and required fields for all our FDX-aligned spec endpoints

Please reach out to the Plaid team for implementation questions not addressed in this documentation.

#### Benefits of building with Core Exchange 

When you build your API with Plaid, your customers will gain access to Plaid's extensive network of financial apps, the largest of any aggregator. You will also benefit from having an API that is interoperable with other organizations that comply with Financial Data Exchange (FDX) API standards.

##### Plaid network 

Once your your API has been successfully validated by Plaid, your organization will appear in [Plaid Link's](https://plaid.comhttps://plaid.com/core-exchange/docs/user-experience/index.html.md) list of available financial institutions. See the [Plaid Link Demo](https://plaid.com/demo/) for a visual walkthrough of your customer’s experience.

(An image of "Plaid Link bank selection")

##### Interoperability 

Plaid’s spec is a subset of the [Financial Data Exchange](https://plaid.com/resources/api/what-is-fdx/) (FDX) API standard. FDX is the common standard for financial data networks (including the Plaid network). This means that when you build an FDX-aligned API with Plaid, you will be able to connect it to Plaid’s extensive ecosystem of fintech apps as well as to other financial data aggregators and organizations.

##### Simplified implementation 

Plaid’s free open finance solution allows you to streamline and validate your API implementation.

With one dedicated engineer in your organization, building an FDX-aligned API with Plaid can typically be completed in six to eight weeks from the date all approvals and resources are in place for your organization. This estimated timeline covers the time period for building, testing, and deployment. It doesn't cover your institution's internal review and approval process, migrating existing integrations, or other considerations included in this document.

#### API flow overview 

At a [high level](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#authorization-flow) , the Plaid network sends your API [secure requests](https://plaid.comhttps://plaid.com/core-exchange/docs/index.html.md#security-flow) for account balance and transaction information.

##### Security flow 

Plaid uses your [OpenID Connect security flow](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#authorization-flow) to allow your customers to connect their financial accounts to their other financial applications.

##### Plaid requests account information 

The first time one of your customers connects their account to the Plaid network, Plaid will send a request for a transaction history period of two years. Afterward, Plaid will send periodic requests for a transaction history period of 14 days. Plaid will also periodically request other account information, including current balances, available balances, liabilities, and statements.

The most common accounts are:

*   Deposit accounts
*   Investment accounts
*   Loan accounts (most commonly STUDENTLOAN and MORTGAGE)
*   Line of credit accounts (most commonly CREDITCARD)

#### Security and privacy 

Plaid has established security and privacy processes to help keep your customer's data secure. See the [Plaid Security Portal](https://security.plaid.com/) for more information.

---


# Mock server | Plaid Docs

Plaid Core Exchange Mock Server 
================================

#### Mock bank server 

Use our mock bank server to understand the subset of FDX information that Plaid consumes. This mock server uses hardcoded public bearer tokens. Remember that in production, bearer tokens must be secure.

See the following Postman collection:

Or, skip Postman and make a few example cURL calls directly to the mock server in a command line:

| Action | Example call |
| --- | --- |
| [List all accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts) for the test user | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts' --header 'Authorization: Bearer 000000000001'` |
| [Get the balance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountid) of the test user's checking account | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/deposit_01_checking' --header 'Authorization: Bearer 000000000001'` |
| [List the transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidtransactions) on the test user's checking account | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/deposit_01_checking/transactions?startTime=2022-01-30&endTime=2022-05-30' --header 'Authorization: Bearer 000000000001'` |
| [List the supported payment networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidpayment-networks) for the test user's savings account | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/deposit_02_savings/payment-networks' --header 'Authorization: Bearer 000000000001'` |
| [Get the contact info](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountid) on the test user's savings account | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/deposit_02_savings/contact' --header 'Authorization: Bearer 000000000001'` |
| [Get the balance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountid) of the test user's mortgage account | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/loan_02_mortgage' --header 'Authorization: Bearer 000000000001'` |
| [Get the balance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountid) of the test user's credit card | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/loc_01_creditcard' --header 'Authorization: Bearer 000000000001'` |
| [List the transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidtransactions) on the test user's credit card | `curl --request GET 'https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/loc_01_creditcard/transactions?startTime=2022-01-30&endTime=2022-05-30' --header 'Authorization: Bearer 000000000001'` |
| [List available account statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidstatements) for the test user's checking account | `curl --request GET https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/deposit_01_checking/statements --header 'Authorization: Bearer 000000000001'` |
| [Get a single account statement PDF](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidstatementsstatementid) from the test user's checking account | `curl --request GET https://api.firstplaidypusbank.plaid.com/fdx/v6/accounts/deposit_01_checking/statements/000001 --header 'Authorization: Bearer 000000000001'` |

---


# 4.6 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v4.6 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY_JOINT_TENANTS`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `SECONDARY`, `SECONDARY_JOINT_TENANTS`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[state](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-state)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AN`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BM`, `BN`, `BO`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CS`, `CU`, `CV`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `ST`, `SV`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-response-page-totalElements)

integer

Total number of elements

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "depositAccount": {
        "accountId": "depositAccount0000001",
        "accountType": "CHECKING",
        "accountNumberDisplay": "5820",
        "productName": "Checking",
        "nickname": "Main Checking",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "loanAccount": {
        "accountId": "loanAccount0000001",
        "accountType": "LOAN",
        "accountNumberDisplay": "4704",
        "productName": "Loan",
        "nickname": "Primary Loan",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "locAccount": {
        "accountId": "locAccount0000001",
        "accountType": "LINEOFCREDIT",
        "accountNumberDisplay": "8200",
        "productName": "Line of Credit",
        "nickname": "First plaidypus LOC",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "investmentAccount": {
        "accountId": "investmentAccount0000001",
        "accountType": "TAXABLE",
        "accountNumberDisplay": "1050",
        "productName": "Brokerage Account",
        "nickname": "First plaidypus Brokerage",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    }
  ]
}
```

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

###### 200 OK 

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

###### 200 OK 

A 200 response will return a PDF account statement.

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-response-page-totalElements)

integer

Total number of elements

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "depositTransaction": {
        "checkNumber": 1234,
        "payee": "ACME llc",
        "transactionId": "depositTransaction000000001",
        "postedTimestamp": "2022-04-06T00:00:00.000Z",
        "transactionTimestamp": "2022-04-05T00:00:00.000Z",
        "description": "check for latest ACME invoice",
        "debitCreditMemo": "DEBIT",
        "status": "PENDING",
        "amount": 400
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000002",
        "postedTimestamp": "2022-04-07T00:00:00.000Z",
        "transactionTimestamp": "2022-04-07T00:00:00.000Z",
        "description": "reconciliation/adjustment of bank statement error",
        "debitCreditMemo": "DEBIT",
        "status": "POSTED",
        "amount": 0.8
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000003",
        "postedTimestamp": "2022-04-08T00:00:00.000Z",
        "transactionTimestamp": "2022-04-08T00:00:00.000Z",
        "description": "ATM cash deposit location #1234",
        "debitCreditMemo": "CREDIT",
        "status": "POSTED",
        "amount": 101.8
      }
    }
  ]
}
```

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-page-totalElements)

integer

Total number of elements

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System

  
  

Possible values: `US_ACH`, `US_FEDWIRE`, `US_CHIPS`, `CA_ACSS`, `CA_LVTS`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following accounts types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `ESOP`, `GUARDIAN`, `INSTITUTIONALTRUST`, `IRA`, `KEOGH`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `SARSEP`, `TAXABLE`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2,
  "holdings": [
    {
      "securityId": "123456789",
      "securityIdType": "CUSIP",
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01T14:46:41.000Z",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15T14:46:41.375Z",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15T14:46:41.375Z",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15T14:46:41.375Z",
  "maturityDate": "2021-07-15T14:46:41.375Z",
  "interestRate": 6.99,
  "interestRateType": "FIXED"
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-nextPaymentDate)

string

Due date of next payment  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-lastStmtDate)

string

Last statement date  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15T14:46:41.375Z",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15T14:46:41.375Z",
  "lastStmtDate": "2021-07-15T14:46:41.375Z"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Commercial account descriptor 

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `ESOP`, `GUARDIAN`, `INSTITUTIONALTRUST`, `IRA`, `KEOGH`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `SARSEP`, `TAXABLE`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Account status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Commercial account types 

The `accountType` field for commercial accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `COMMERCIALDEPOSIT` | A deposit account for commercial customers, for example a business trust account |
| `COMMERCIALLOAN` | A preset borrowing limit that can be used at any time |
| `COMMERCIALLINEOFCREDIT` | An account with a preset borrowing limit that can be used at any time |
| `COMMERCIALINVESTMENT` | Investment Account for Commercial Customers. e.g. Commercial Brokerage Account |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md#LocTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 5.0 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v5.0 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY_JOINT_TENANTS`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `SECONDARY`, `SECONDARY_JOINT_TENANTS`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AN`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BM`, `BN`, `BO`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CS`, `CU`, `CV`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `ST`, `SV`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "depositAccount": {
        "accountId": "depositAccount0000001",
        "accountType": "CHECKING",
        "accountNumberDisplay": "5820",
        "productName": "Checking",
        "nickname": "Main Checking",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "loanAccount": {
        "accountId": "loanAccount0000001",
        "accountType": "LOAN",
        "accountNumberDisplay": "4704",
        "productName": "Loan",
        "nickname": "Primary Loan",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "locAccount": {
        "accountId": "locAccount0000001",
        "accountType": "LINEOFCREDIT",
        "accountNumberDisplay": "8200",
        "productName": "Line of Credit",
        "nickname": "First plaidypus LOC",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "investmentAccount": {
        "accountId": "investmentAccount0000001",
        "accountType": "TAXABLE",
        "accountNumberDisplay": "1050",
        "productName": "Brokerage Account",
        "nickname": "First plaidypus Brokerage",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

###### 200 OK 

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

###### 200 OK 

A 200 response will return a PDF account statement.

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "depositTransaction": {
        "checkNumber": 1234,
        "payee": "ACME llc",
        "transactionId": "depositTransaction000000001",
        "postedTimestamp": "2022-04-06T00:00:00.000Z",
        "transactionTimestamp": "2022-04-05T00:00:00.000Z",
        "description": "check for latest ACME invoice",
        "debitCreditMemo": "DEBIT",
        "status": "PENDING",
        "amount": 400
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000002",
        "postedTimestamp": "2022-04-07T00:00:00.000Z",
        "transactionTimestamp": "2022-04-07T00:00:00.000Z",
        "description": "reconciliation/adjustment of bank statement error",
        "debitCreditMemo": "DEBIT",
        "status": "POSTED",
        "amount": 0.8
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000003",
        "postedTimestamp": "2022-04-08T00:00:00.000Z",
        "transactionTimestamp": "2022-04-08T00:00:00.000Z",
        "description": "ATM cash deposit location #1234",
        "debitCreditMemo": "CREDIT",
        "status": "POSTED",
        "amount": 101.8
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System

  
  

Possible values: `US_ACH`, `US_FEDWIRE`, `US_CHIPS`, `CA_ACSS`, `CA_LVTS`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following accounts types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `ESOP`, `GUARDIAN`, `INSTITUTIONALTRUST`, `IRA`, `KEOGH`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `SARSEP`, `TAXABLE`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2,
  "holdings": [
    {
      "securityId": "123456789",
      "securityIdType": "CUSIP",
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99,
  "interestRateType": "FIXED"
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `ESOP`, `GUARDIAN`, `INSTITUTIONALTRUST`, `IRA`, `KEOGH`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `SARSEP`, `TAXABLE`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |
| `RESTRICTED` | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md#LocTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 5.1 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v5.1 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY_JOINT_TENANTS`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `SECONDARY`, `SECONDARY_JOINT_TENANTS`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AN`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BM`, `BN`, `BO`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CS`, `CU`, `CV`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `ST`, `SV`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-response-page-totalElements)

integer

Total number of elements

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "depositAccount": {
        "accountId": "depositAccount0000001",
        "accountType": "CHECKING",
        "accountNumberDisplay": "5820",
        "productName": "Checking",
        "nickname": "Main Checking",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "loanAccount": {
        "accountId": "loanAccount0000001",
        "accountType": "LOAN",
        "accountNumberDisplay": "4704",
        "productName": "Loan",
        "nickname": "Primary Loan",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "locAccount": {
        "accountId": "locAccount0000001",
        "accountType": "LINEOFCREDIT",
        "accountNumberDisplay": "8200",
        "productName": "Line of Credit",
        "nickname": "First plaidypus LOC",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "investmentAccount": {
        "accountId": "investmentAccount0000001",
        "accountType": "TAXABLE",
        "accountNumberDisplay": "1050",
        "productName": "Brokerage Account",
        "nickname": "First plaidypus Brokerage",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-response-page-totalElements)

integer

Total number of elements

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "depositTransaction": {
        "checkNumber": 1234,
        "payee": "ACME llc",
        "transactionId": "depositTransaction000000001",
        "postedTimestamp": "2022-04-06T00:00:00.000Z",
        "transactionTimestamp": "2022-04-05T00:00:00.000Z",
        "description": "check for latest ACME invoice",
        "debitCreditMemo": "DEBIT",
        "status": "PENDING",
        "amount": 400
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000002",
        "postedTimestamp": "2022-04-07T00:00:00.000Z",
        "transactionTimestamp": "2022-04-07T00:00:00.000Z",
        "description": "reconciliation/adjustment of bank statement error",
        "debitCreditMemo": "DEBIT",
        "status": "POSTED",
        "amount": 0.8
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000003",
        "postedTimestamp": "2022-04-08T00:00:00.000Z",
        "transactionTimestamp": "2022-04-08T00:00:00.000Z",
        "description": "ATM cash deposit location #1234",
        "debitCreditMemo": "CREDIT",
        "status": "POSTED",
        "amount": 101.8
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-page-totalElements)

integer

Total number of elements

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System
*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_RTP: US Real Time Payments System

  
  

Possible values: `US_ACH`, `US_FEDWIRE`, `US_CHIPS`, `US_RTP`, `CA_ACSS`, `CA_LVTS`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following accounts types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `ESOP`, `GUARDIAN`, `INSTITUTIONALTRUST`, `IRA`, `KEOGH`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `SARSEP`, `TAXABLE`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2,
  "holdings": [
    {
      "securityId": "123456789",
      "securityIdType": "CUSIP",
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99,
  "interestRateType": "FIXED"
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `ESOP`, `GUARDIAN`, `INSTITUTIONALTRUST`, `IRA`, `KEOGH`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `SARSEP`, `TAXABLE`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| CLOSED | An account that is closed or no longer exists |
| DELINQUENT | An account with unpaid payments that are past due |
| NEGATIVECURRENTBALANCE | An account with a current negative balance |
| PAID | An account that is paid in full |
| PENDINGCLOSE | An account that is in the process of being closed |
| PENDINGOPEN | An account that is in the process of being opened |
| RESTRICTED | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  

*   `ADJUSTMENT`: Adjustment or correction.
*   `FEE`: Fee charge. For example, a late payment fee.
*   `INTEREST`: Interest charge.
*   `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages).
*   `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time.
*   `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment.
*   `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal.
*   `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md#LocTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 5.2 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v5.2 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accountsaccountidstatements) | Get account statements |
| [/accounts/{accountId}/statements/{statementId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accountsaccountidstatementsstatementid) | Get account statement PDF |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY_JOINT_TENANTS`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `SECONDARY`, `SECONDARY_JOINT_TENANTS`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AN`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BM`, `BN`, `BO`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CS`, `CU`, `CV`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `ST`, `SV`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-response-page-totalElements)

integer

Total number of elements

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "depositAccount": {
        "accountId": "depositAccount0000001",
        "accountType": "CHECKING",
        "accountNumberDisplay": "5820",
        "productName": "Checking",
        "nickname": "Main Checking",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "loanAccount": {
        "accountId": "loanAccount0000001",
        "accountType": "LOAN",
        "accountNumberDisplay": "4704",
        "productName": "Loan",
        "nickname": "Primary Loan",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "locAccount": {
        "accountId": "locAccount0000001",
        "accountType": "LINEOFCREDIT",
        "accountNumberDisplay": "8200",
        "productName": "Line of Credit",
        "nickname": "First plaidypus LOC",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "investmentAccount": {
        "accountId": "investmentAccount0000001",
        "accountType": "TAXABLE",
        "accountNumberDisplay": "1050",
        "productName": "Brokerage Account",
        "nickname": "First plaidypus Brokerage",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

#### Search for statements 

Get account statements.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements?startTime=2022-04-01&endTime=2022-04-30' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-page-totalElements)

integer

Total number of elements

[statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements)

required, \[object\]

An array of statements, each with its own HATEOAS link to retrieve the account statement

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-accountId)

string

Corresponds to `accountId` in Account entity  
  

Max length: `256`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-statementId)

string

Long-term persistent identity of the statement. This identity must be unique within your organization  
  

Max length: `256`

[statementDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-statementDate)

string

The date the statement becomes available to be viewed by the user  
  

Format: `date`

Max length: `10`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-description)

string

Description of the statement

[links](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-links)

\[object\]

The HATEOAS links to retrieve this account statement, or to invoke other APIs.  
**Note:** Plaid only accepts one link object in this array

[href](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-links-href)

required, string

The resource URL  
  

Format: `uri-reference`

[action](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-links-action)

string

The HTTP method to use for the request  
  

Possible values: `GET`, `POST`, `PATCH`, `DELETE`, `PUT`

[rel](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-links-rel)

string

The relation of this link to its containing entity, as defined by the [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)

[types](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-links-types)

\[string\]

The content-types that can be used in the Accept header. **Note:** Plaid currently only accepts the PDF (`application/pdf`) content type  
  

Possible values: `application/pdf`, `image/gif`, `image/jpeg`, `image/tiff`, `image/png`, `application/json`

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-response-statements-status)

string

Availability status of statement  
  

Possible values: `AVAILABLE`, `PROCESSING`, `FAILED`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "total": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "statementDate": "2024-01-15",
      "description": "January 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20001",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        },
        {
          "href": "/accounts/10001/statements/20001/download",
          "rel": "download",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "AVAILABLE"
    },
    {
      "accountId": "10001",
      "statementId": "20002",
      "statementDate": "2024-02-15",
      "description": "February 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20002",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "PROCESSING"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

#### Get account statement 

Get account statement PDF

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-{statementid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-statements-{statementid}-request-statementId)

string

Statement identifier, found in the `GET /accounts/{accountId}/statements` endpoint response  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements/{statementId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return a raw binary PDF statement file.

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-response-page-totalElements)

integer

Total number of elements

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "depositTransaction": {
        "transactionType": "CHECK",
        "checkNumber": 1234,
        "payee": "ACME llc",
        "transactionId": "depositTransaction000000001",
        "postedTimestamp": "2022-04-06T00:00:00.000Z",
        "transactionTimestamp": "2022-04-05T00:00:00.000Z",
        "description": "check for latest ACME invoice",
        "debitCreditMemo": "DEBIT",
        "status": "PENDING",
        "amount": 400
      }
    },
    {
      "depositTransaction": {
        "transactionType": "ADJUSTMENT",
        "transactionId": "depositTransaction000000002",
        "postedTimestamp": "2022-04-07T00:00:00.000Z",
        "transactionTimestamp": "2022-04-07T00:00:00.000Z",
        "description": "reconciliation/adjustment of bank statement error",
        "debitCreditMemo": "DEBIT",
        "status": "POSTED",
        "amount": 0.8
      }
    },
    {
      "depositTransaction": {
        "transactionType": "ATMDEPOSIT",
        "transactionId": "depositTransaction000000003",
        "postedTimestamp": "2022-04-08T00:00:00.000Z",
        "transactionTimestamp": "2022-04-08T00:00:00.000Z",
        "description": "ATM cash deposit location #1234",
        "debitCreditMemo": "CREDIT",
        "status": "POSTED",
        "amount": 101.8
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-page-totalElements)

integer

Total number of elements

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System
*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_RTP: US Real Time Payments System

  
  

Possible values: `US_ACH`, `US_FEDWIRE`, `US_CHIPS`, `US_RTP`, `CA_ACSS`, `CA_LVTS`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following accounts types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `ROLLOVER`, `ROTH`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2,
  "holdings": [
    {
      "securityId": "123456789",
      "securityIdType": "CUSIP",
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99,
  "interestRateType": "FIXED"
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `COMMERCIALDEPOSIT`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COMMERCIALINVESTMENT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `ROLLOVER`, `ROTH`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `COMMERCIALLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-currency-currencyCode)

required, string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `COMMERCIALLINEOFCREDIT`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| CLOSED | An account that is closed or no longer exists |
| DELINQUENT | An account with unpaid payments that are past due |
| NEGATIVECURRENTBALANCE | An account with a current negative balance |
| PAID | An account that is paid in full |
| PENDINGCLOSE | An account that is in the process of being closed |
| PENDINGOPEN | An account that is in the process of being opened |
| RESTRICTED | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  

*   `ADJUSTMENT`: Adjustment or correction.
*   `FEE`: Fee charge. For example, a late payment fee.
*   `INTEREST`: Interest charge.
*   `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages).
*   `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time.
*   `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment.
*   `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal.
*   `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-foreignCurrency)

string

ISO 4217 Currency codes  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UZS`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md#LocTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 5.3 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v5.3 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accountsaccountidstatements) | Get account statements |
| [/accounts/{accountId}/statements/{statmentId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accountsaccountidstatementsstatementid) | Get account statement PDF |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY_JOINT_TENANTS`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `SECONDARY`, `SECONDARY_JOINT_TENANTS`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-response-page-totalElements)

integer

Total number of elements

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [commercialAccount](https://plaid.com#commercial-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "depositAccount": {
        "accountId": "depositAccount0000001",
        "accountType": "CHECKING",
        "accountNumberDisplay": "5820",
        "productName": "Checking",
        "nickname": "Main Checking",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "loanAccount": {
        "accountId": "loanAccount0000001",
        "accountType": "LOAN",
        "accountNumberDisplay": "4704",
        "productName": "Loan",
        "nickname": "Primary Loan",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "locAccount": {
        "accountId": "locAccount0000001",
        "accountType": "LINEOFCREDIT",
        "accountNumberDisplay": "8200",
        "productName": "Line of Credit",
        "nickname": "First plaidypus LOC",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    },
    {
      "investmentAccount": {
        "accountId": "investmentAccount0000001",
        "accountType": "TAXABLE",
        "accountNumberDisplay": "1050",
        "productName": "Brokerage Account",
        "nickname": "First plaidypus Brokerage",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        }
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

#### Search for statements 

Get account statements.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts/{accountId}/statements?startTime=2022-04-01&endTime=2022-04-30' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-page-totalElements)

integer

Total number of elements

[statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements)

required, \[object\]

An array of statements, each with its own HATEOAS link to retrieve the account statement

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-accountId)

string

Corresponds to `accountId` in Account entity  
  

Max length: `256`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-statementId)

string

Long-term persistent identity of the statement. This identity must be unique within your organization  
  

Max length: `256`

[statementDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-statementDate)

string

The date the statement becomes available to be viewed by the user  
  

Format: `date`

Max length: `10`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-description)

string

Description of the statement

[links](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-links)

\[object\]

The HATEOAS links to retrieve this account statement, or to invoke other APIs.  
**Note:** Plaid only accepts one link object in this array

[href](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-links-href)

required, string

The resource URL  
  

Format: `uri-reference`

[action](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-links-action)

string

The HTTP method to use for the request  
  

Possible values: `GET`, `POST`, `PATCH`, `DELETE`, `PUT`

[rel](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-links-rel)

string

The relation of this link to its containing entity, as defined by the [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)

[types](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-links-types)

\[string\]

The content-types that can be used in the Accept header. **Note:** Plaid currently only accepts the PDF (`application/pdf`) content type  
  

Possible values: `application/pdf`, `image/gif`, `image/jpeg`, `image/tiff`, `image/png`, `application/json`

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-response-statements-status)

string

Availability status of statement  
  

Possible values: `AVAILABLE`, `PROCESSING`, `FAILED`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "total": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "statementDate": "2024-01-15",
      "description": "January 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20001",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        },
        {
          "href": "/accounts/10001/statements/20001/download",
          "rel": "download",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "AVAILABLE"
    },
    {
      "accountId": "10001",
      "statementId": "20002",
      "statementDate": "2024-02-15",
      "description": "February 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20002",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "PROCESSING"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

#### Get account statement 

Get account statement PDF

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-{statementid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-statements-{statementid}-request-statementId)

string

Statement identifier, found in the `GET /accounts/{accountId}/statements` endpoint response  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts/{accountId}/statements/{statementId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return a raw binary PDF statement file.

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-response-page-totalElements)

integer

Total number of elements

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "depositTransaction": {
        "checkNumber": 1234,
        "payee": "ACME llc",
        "transactionId": "depositTransaction000000001",
        "postedTimestamp": "2022-04-06T00:00:00.000Z",
        "transactionTimestamp": "2022-04-05T00:00:00.000Z",
        "description": "check for latest ACME invoice",
        "debitCreditMemo": "DEBIT",
        "status": "PENDING",
        "amount": 400
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000002",
        "postedTimestamp": "2022-04-07T00:00:00.000Z",
        "transactionTimestamp": "2022-04-07T00:00:00.000Z",
        "description": "reconciliation/adjustment of bank statement error",
        "debitCreditMemo": "DEBIT",
        "status": "POSTED",
        "amount": 0.8
      }
    },
    {
      "depositTransaction": {
        "transactionId": "depositTransaction000000003",
        "postedTimestamp": "2022-04-08T00:00:00.000Z",
        "transactionTimestamp": "2022-04-08T00:00:00.000Z",
        "description": "ATM cash deposit location #1234",
        "debitCreditMemo": "CREDIT",
        "status": "POSTED",
        "amount": 101.8
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-organization.plaid.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-page-totalElements)

integer

Total number of elements

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System
*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_RTP: US Real Time Payments System

  
  

Possible values: `US_ACH`, `US_FEDWIRE`, `US_CHIPS`, `US_RTP`, `CA_ACSS`, `CA_LVTS`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following accounts types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2,
  "holdings": [
    {
      "securityId": "123456789",
      "securityIdType": "CUSIP",
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99,
  "interestRateType": "FIXED"
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Commercial account descriptor 

A commercial account. For example, a business deposit account. The `accountType` field for commercial accounts may be set to any of the [account types](https://plaid.com#commercial-account-types) listed below

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#CommercialAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `COMMERCIALDEPOSIT`, `COMMERCIALINVESTMENT`, `COMMERCIALLOAN`, `COMMERCIALLINEOFCREDIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "COMMERCIALLOAN"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "5921",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |
| `RESTRICTED` | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Commercial account types 

The `accountType` field for accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `COMMERCIALDEPOSIT` | A deposit account for commercial customers, for example a business trust account |
| `COMMERCIALLOAN` | A preset borrowing limit that can be used at any time |
| `COMMERCIALLINEOFCREDIT` | An account with a preset borrowing limit that can be used at any time |
| `COMMERCIALINVESTMENT` | Investment Account for Commercial Customers. e.g. Commercial Brokerage Account |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CUSIP`, `ISIN`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  

*   `ADJUSTMENT`: Adjustment or correction.
*   `FEE`: Fee charge. For example, a late payment fee.
*   `INTEREST`: Interest charge.
*   `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages).
*   `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time.
*   `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment.
*   `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal.
*   `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `PURCHASE`, `WITHDRAWAL`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md#LocTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "transactionId": "someLongTermUniqueIDString",
  "referenceTransactionId": "someLongTermUniqueIDString",
  "postedTimestamp": "2021-07-15T14:46:41.375Z",
  "transactionTimestamp": "2021-07-15T14:46:41.375Z",
  "foreignCurrency": "CAD"
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, but rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, but rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 6.0 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v6.0 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountidstatements) | Get account statements |
| [/accounts/{accountId}/statements/{statementId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountidstatementsstatementid) | Get account statement PDF |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |
| [/accounts/{accountId}/asset-transfer-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accountsaccountidasset-transfer-networks) | Get asset transfer networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `PRIMARY_JOINT_TENANTS`, `SECONDARY`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SECONDARY_JOINT_TENANTS`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-response-page-totalElements)

integer

Total number of elements

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [commercialAccount](https://plaid.com#commercial-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investment account](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "accountId": "depositAccount0000001",
      "accountType": "CHECKING",
      "accountNumberDisplay": "5820",
      "productName": "Checking",
      "nickname": "Main Checking",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOAN_ACCOUNT",
      "accountId": "loanAccount0000001",
      "accountType": "LOAN",
      "accountNumberDisplay": "4704",
      "productName": "Loan",
      "nickname": "Primary Loan",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOC_ACCOUNT",
      "accountId": "locAccount0000001",
      "accountType": "LINEOFCREDIT",
      "accountNumberDisplay": "8200",
      "productName": "Line of Credit",
      "nickname": "First plaidypus LOC",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "INVESTMENT_ACCOUNT",
      "accountId": "investmentAccount0000001",
      "accountType": "TAXABLE",
      "accountNumberDisplay": "1050",
      "productName": "Brokerage Account",
      "nickname": "First plaidypus Brokerage",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#loan-account)

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

#### Search for statements 

Get account statements.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements?startTime=2022-04-01&endTime=2022-04-30' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-page-totalElements)

integer

Total number of elements

[statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements)

required, \[object\]

An array of statements, each with its own HATEOAS link to retrieve the account statement

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-accountId)

string

Corresponds to `accountId` in Account entity  
  

Max length: `256`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-statementId)

string

Long-term persistent identity of the statement. This identity must be unique within your organization  
  

Max length: `256`

[statementDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-statementDate)

string

The date the statement becomes available to be viewed by the user  
  

Format: `date`

Max length: `10`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-description)

string

Description of the statement

[links](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-links)

\[object\]

The HATEOAS links to retrieve this account statement, or to invoke other APIs.  
**Note:** Plaid only accepts one link object in this array

[href](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-links-href)

required, string

The resource URL  
  

Format: `uri-reference`

[action](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-links-action)

string

The HTTP method to use for the request  
  

Possible values: `GET`, `POST`, `PATCH`, `DELETE`, `PUT`

[rel](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-links-rel)

string

The relation of this link to its containing entity, as defined by the [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)

[types](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-links-types)

\[string\]

The content-types that can be used in the Accept header. **Note:** Plaid currently only accepts the PDF (`application/pdf`) content type  
  

Possible values: `application/pdf`, `image/gif`, `image/jpeg`, `image/tiff`, `image/png`, `application/json`

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-response-statements-status)

string

Availability status of statement  
  

Possible values: `AVAILABLE`, `PROCESSING`, `FAILED`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "total": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "statementDate": "2024-01-15",
      "description": "January 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20001",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        },
        {
          "href": "/accounts/10001/statements/20001/download",
          "rel": "download",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "AVAILABLE"
    },
    {
      "accountId": "10001",
      "statementId": "20002",
      "statementDate": "2024-02-15",
      "description": "February 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20002",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "PROCESSING"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

#### Get account statement 

Get account statement PDF

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-{statementid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-statements-{statementid}-request-statementId)

string

Statement identifier, found in the `GET /accounts/{accountId}/statements` endpoint response  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements/{statementId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return a raw binary PDF statement file.

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-response-page-totalElements)

integer

Total number of elements

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "checkNumber": 1234,
      "payee": "ACME LLC",
      "transactionId": "depositTransaction000000001",
      "postedTimestamp": "2022-04-06T00:00:00.000Z",
      "transactionTimestamp": "2022-04-05T00:00:00.000Z",
      "description": "check for latest ACME invoice",
      "debitCreditMemo": "DEBIT",
      "status": "PENDING",
      "amount": 400
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionId": "depositTransaction000000002",
      "postedTimestamp": "2022-04-07T00:00:00.000Z",
      "transactionTimestamp": "2022-04-07T00:00:00.000Z",
      "description": "reconciliation/adjustment of bank statement error",
      "debitCreditMemo": "DEBIT",
      "status": "POSTED",
      "amount": 0.8
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionId": "depositTransaction000000003",
      "postedTimestamp": "2022-04-08T00:00:00.000Z",
      "transactionTimestamp": "2022-04-08T00:00:00.000Z",
      "description": "ATM cash deposit location #1234",
      "debitCreditMemo": "CREDIT",
      "status": "POSTED",
      "amount": 101.8
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-page-totalElements)

integer

Total number of elements

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System
*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   US\_FEDNOW: Federal Reserve Instant Payment System
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_RTP: US Real Time Payments System

  
  

Possible values: `CA_ACSS`, `CA_LVTS`, `US_ACH`, `US_CHIPS`, `US_FEDNOW`, `US_FEDWIRE`, `US_RTP`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/asset-transfer-networks 

#### Get asset transfer details for this account 

Get asset transfer networks supported by an account. For example, Automated Customer Account Transfer Service (ACATS). For more information about how Plaid uses this information, see the [Plaid Investments Move API](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/asset-transfer-networks?limit=25' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[assetTransferNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks)

required, \[object\]

A paginated array of asset transfer networks for the account

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifier)

required, string

The number used to identify the account within the asset transfer network. If identifierType is ACCOUNT_NUMBER, this is the account number; if identifierType is TOKENIZED_ACCOUNT_NUMBER, this is a tokenized account number_

[identifierType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifierType)

string

The type of identifier used to identify the account in the payment network  
  

Possible values: `ACCOUNT_NUMBER`, `TOKENIZED_ACCOUNT_NUMBER`

[institutionName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionName)

string

The name of the institution holding the account

[institutionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionId)

required, string

Institution identifier used by the asset transfer network ie. the Depository Trust and Clearing Corporation code for the institution holding the account

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-type)

required, string

The type of asset transfer  
  

Possible values: `CA_ATON`, `US_ACATS`, `US_DTC`

[jointAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-jointAccount)

boolean

Whether this account has joint owners

```json
{
  "assetTransferNetworks": [
    {
      "identifier": "23348817826",
      "identifierType": "ACCOUNT_NUMBER",
      "institutionName": "First Plaidypus Bank",
      "institutionId": "FPB",
      "type": "US_ACATS",
      "jointAccount": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following account types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1832.11,
  "availableBalance": 1832.11
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityIds](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-securityIds)

\[object\]

Array of security identifiers

[id](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-securityIds-id)

string

Value for a unique identifier  
  

Max length: `256`

[idType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-securityIds-idType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 8302.18,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 3702.19,
  "holdings": [
    {
      "securityIds": [
        {
          "id": "123456789",
          "idType": "CUSIP"
        }
      ],
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestPaidYearToDate": 403.04,
  "interestRate": 6.99,
  "interestRateType": "FIXED"
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "creditLine": 2,
  "availableCredit": 8302.73,
  "nextPaymentAmount": 1832.11,
  "nextPaymentDate": "2021-07-15",
  "principalBalance": 132.28,
  "currentBalance": 892.1,
  "minimumPaymentAmount": 190.32,
  "lastPaymentAmount": 2852.91,
  "lastPaymentDate": "2021-07-15",
  "pastDueAmount": 0,
  "lastStmtBalance": 5393.81,
  "lastStmtDate": "2021-07-15",
  "purchasesApr": 0,
  "advancesApr": 0
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `ANNUITY_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "ANNUITY_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Commercial account descriptor 

A commercial account. For example, a business deposit account. The `accountType` field for commercial accounts may be set to any of the [account types](https://plaid.com#commercial-account-types) listed below

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `COMMERCIAL_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#CommercialAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `COMMERCIALDEPOSIT`, `COMMERCIALINVESTMENT`, `COMMERCIALLOAN`, `COMMERCIALLINEOFCREDIT`

```json
{
  "accountCategory": "COMMERCIAL_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "COMMERCIALLOAN"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INSURANCE_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountCategory": "INSURANCE_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |
| `RESTRICTED` | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Commercial account types 

The `accountType` field for accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `COMMERCIALDEPOSIT` | A deposit account for commercial customers, for example a business trust account |
| `COMMERCIALLOAN` | A preset borrowing limit that can be used at any time |
| `COMMERCIALLINEOFCREDIT` | An account with a preset borrowing limit that can be used at any time |
| `COMMERCIALINVESTMENT` | Investment Account for Commercial Customers. e.g. Commercial Brokerage Account |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "ATM deposit",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 38.9
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Share purchase",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 428.08,
  "fees": 4.28,
  "transactionType": "PURCHASED"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  

*   `ADJUSTMENT`: Adjustment or correction.
*   `FEE`: Fee charge. For example, a late payment fee.
*   `INTEREST`: Interest charge.
*   `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages).
*   `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time.
*   `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment.
*   `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal.
*   `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Monthly loan payment-minimum due",
  "debitCreditMemo": "CREDIT",
  "status": "POSTED",
  "amount": 1638.83
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`, `PURCHASE`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md#LineOfCreditTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Recurring payment",
  "debitCreditMemo": "MEMO",
  "status": "AUTHORIZATION",
  "amount": 38.9
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 6.1 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v6.1 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidstatements) | Get account statements |
| [/accounts/{accountId}/statements/{statementId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidstatementsstatementid) | Get account statement PDF |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |
| [/accounts/{accountId}/asset-transfer-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accountsaccountidasset-transfer-networks) | Get asset transfer networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `PRIMARY_JOINT_TENANTS`, `SECONDARY`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SECONDARY_JOINT_TENANTS`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-response-page-totalElements)

integer

Total number of elements

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [commercialAccount](https://plaid.com#commercial-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investment account](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "accountId": "depositAccount0000001",
      "accountType": "CHECKING",
      "accountNumberDisplay": "5820",
      "productName": "Checking",
      "nickname": "Main Checking",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOAN_ACCOUNT",
      "accountId": "loanAccount0000001",
      "accountType": "LOAN",
      "accountNumberDisplay": "4704",
      "productName": "Loan",
      "nickname": "Primary Loan",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOC_ACCOUNT",
      "accountId": "locAccount0000001",
      "accountType": "LINEOFCREDIT",
      "accountNumberDisplay": "8200",
      "productName": "Line of Credit",
      "nickname": "First plaidypus LOC",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "INVESTMENT_ACCOUNT",
      "accountId": "investmentAccount0000001",
      "accountType": "TAXABLE",
      "accountNumberDisplay": "1050",
      "productName": "Brokerage Account",
      "nickname": "First plaidypus Brokerage",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`. The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

#### Search for statements 

Get account statements.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements?startTime=2022-04-01&endTime=2022-04-30' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-page-totalElements)

integer

Total number of elements

[statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements)

required, \[object\]

An array of statements, each with its own HATEOAS link to retrieve the account statement

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-accountId)

string

Corresponds to `accountId` in Account entity  
  

Max length: `256`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-statementId)

string

Long-term persistent identity of the statement. This identity must be unique within your organization  
  

Max length: `256`

[statementDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-statementDate)

string

The date the statement becomes available to be viewed by the user  
  

Format: `date`

Max length: `10`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-description)

string

Description of the statement

[links](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-links)

\[object\]

The HATEOAS links to retrieve this account statement, or to invoke other APIs. **Note:** Plaid only accepts one link object in this array

[href](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-links-href)

required, string

The resource URL  
  

Format: `uri-reference`

[action](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-links-action)

string

The HTTP method to use for the request  
  

Possible values: `GET`, `POST`, `PATCH`, `DELETE`, `PUT`

[rel](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-links-rel)

string

The relation of this link to its containing entity, as defined by the [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)

[types](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-links-types)

\[string\]

The content-types that can be used in the Accept header. **Note:** Plaid currently only accepts the PDF (`application/pdf`) content type  
  

Possible values: `application/pdf`, `image/gif`, `image/jpeg`, `image/tiff`, `image/png`, `application/json`

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-response-statements-status)

string

Availability status of statement  
  

Possible values: `AVAILABLE`, `PROCESSING`, `FAILED`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "total": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "statementDate": "2024-01-15",
      "description": "January 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20001",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        },
        {
          "href": "/accounts/10001/statements/20001/download",
          "rel": "download",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "AVAILABLE"
    },
    {
      "accountId": "10001",
      "statementId": "20002",
      "statementDate": "2024-02-15",
      "description": "February 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20002",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "PROCESSING"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

#### Get account statement 

Get account statement PDF

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-{statementid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-statements-{statementid}-request-statementId)

string

Statement identifier, found in the `GET /accounts/{accountId}/statements` endpoint response  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements/{statementId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return a raw binary PDF statement file.

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-response-page-totalElements)

integer

Total number of elements

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "checkNumber": 1234,
      "payee": "ACME LLC",
      "transactionId": "depositTransaction000000001",
      "postedTimestamp": "2022-04-06T00:00:00.000Z",
      "transactionTimestamp": "2022-04-05T00:00:00.000Z",
      "description": "check for latest ACME invoice",
      "debitCreditMemo": "DEBIT",
      "status": "PENDING",
      "amount": 400
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionId": "depositTransaction000000002",
      "postedTimestamp": "2022-04-07T00:00:00.000Z",
      "transactionTimestamp": "2022-04-07T00:00:00.000Z",
      "description": "reconciliation/adjustment of bank statement error",
      "debitCreditMemo": "DEBIT",
      "status": "POSTED",
      "amount": 0.8
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionId": "depositTransaction000000003",
      "postedTimestamp": "2022-04-08T00:00:00.000Z",
      "transactionTimestamp": "2022-04-08T00:00:00.000Z",
      "description": "ATM cash deposit location #1234",
      "debitCreditMemo": "CREDIT",
      "status": "POSTED",
      "amount": 101.8
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[totalElements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-page-totalElements)

integer

Total number of elements

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:

*   CA\_ACSS: Automated Clearing House Settlement System _CA\_LVTS: Large-Value Transfer System_ US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks) _US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)_ US\_FEDNOW: Federal Reserve Instant Payment System _US\_FEDWIRE: Fedwire Funds Service_ US\_RTP: US Real Time Payments System

  
  

Possible values: `CA_ACSS`, `CA_LVTS`, `US_ACH`, `US_CHIPS`, `US_FEDNOW`, `US_FEDWIRE`, `US_RTP`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not. **Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not. **Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/asset-transfer-networks 

#### Get asset transfer details for this account 

Get asset transfer networks supported by an account. For example, Automated Customer Account Transfer Service (ACATS). For more information about how Plaid uses this information, see the [Plaid Investments Move API](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number **Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/asset-transfer-networks?limit=25' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[assetTransferNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks)

required, \[object\]

A paginated array of asset transfer networks for the account

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifier)

required, string

The number used to identify the account within the asset transfer network. If identifierType is ACCOUNT_NUMBER, this is the account number; if identifierType is TOKENIZED_ACCOUNT_NUMBER, this is a tokenized account number_

[identifierType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifierType)

string

The type of identifier used to identify the account in the payment network  
  

Possible values: `ACCOUNT_NUMBER`, `TOKENIZED_ACCOUNT_NUMBER`

[institutionName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionName)

string

The name of the institution holding the account

[institutionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionId)

required, string

Institution identifier used by the asset transfer network ie. the Depository Trust and Clearing Corporation code for the institution holding the account

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-type)

required, string

The type of asset transfer  
  

Possible values: `CA_ATON`, `US_ACATS`, `US_DTC`

[jointAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-jointAccount)

boolean

Whether this account has joint owners

```json
{
  "assetTransferNetworks": [
    {
      "identifier": "23348817826",
      "identifierType": "ACCOUNT_NUMBER",
      "institutionName": "First Plaidypus Bank",
      "institutionId": "FPB",
      "type": "US_ACATS",
      "jointAccount": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following account types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`. The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityIds](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-securityIds)

\[object\]

Array of security identifiers

[id](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-securityIds-id)

string

Value for a unique identifier  
  

Max length: `256`

[idType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-securityIds-idType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL. This field, along with `securityId` are **required** unless `symbol` is provided. **Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options. **Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2,
  "holdings": [
    {
      "securityIds": [
        {
          "id": "123456789",
          "idType": "CUSIP"
        }
      ],
      "holdingName": "Apple Inc.",
      "holdingType": "STOCK",
      "holdingSubType": "CASH",
      "symbol": "AAPL",
      "purchasedPrice": 150,
      "currentUnitPrice": 175,
      "currentUnitPriceDate": "2023-10-01",
      "units": 1,
      "marketValue": 1750,
      "cashAccount": true,
      "currency": {
        "currencyCode": "USD"
      },
      "fiAttributes": [
        {
          "name": "isCashEquivalent",
          "value": "false"
        }
      ]
    }
  ]
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below. Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below: Required for all loan accounts: _`principalBalance`_ `interestRate` _`interestRateType` Optional fields for `STUDENTLOAN` accounts:_ `interestPaidYearToDate` _`lastPaymentAmount`_ `lastPaymentDate` _`maturityDate`_ `nextPaymentDate` _`originalPrincipal`_ `originatingDate` Required for `MORTGAGE` accounts: _`accountNumber` Optional fields for `MORTGAGE` accounts:_ `escrowBalance` _`interestPaidYearToDate`_ `lastPaymentAmount` _`lastPaymentDate`_ `loanTerm` _`maturityDate`_ `nextPaymentAmount` _`nextPaymentDate`_ `originalPrincipal` _`originatingDate` Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`_

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-originatingDate)

string

Date loan originated ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-maturityDate)

string

Maturity date ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below. Plaid may consume all the parameters returned by the `GET /accounts` endpoint:

*   `availableCredit` _`creditLine`_ `currentBalance`

Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:

*   `advancesApr` _`lastPaymentAmount`_ `lastPaymentDate` _`lastStmtBalance`_ `lastStmtDate` _`minimumPaymentAmount`_ `nextPaymentDate` _`purchasesApr` Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`_

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-lastPaymentDate)

string

Last payment date ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-lastStmtDate)

string

Last statement date ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account. The `accountType` field for annuity accounts may be set to any of the following:

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums. - `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account. - `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `ANNUITY_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "ANNUITY_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Commercial account descriptor 

A commercial account. For example, a business deposit account. The `accountType` field for commercial accounts may be set to any of the [account types](https://plaid.com#commercial-account-types) listed below

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `COMMERCIAL_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#CommercialAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `COMMERCIALDEPOSIT`, `COMMERCIALINVESTMENT`, `COMMERCIALLOAN`, `COMMERCIALLINEOFCREDIT`

```json
{
  "accountCategory": "COMMERCIAL_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "COMMERCIALLOAN"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts. The `accountType` field for deposit accounts may be set to any of the following:

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits. - `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution. - `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time. - `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account. - `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties. - `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets. - `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability. The `accountType` field for insurance accounts may be set to any of the following:

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year. - `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year. - `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest. - `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INSURANCE_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountCategory": "INSURANCE_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts. The `accountType` field for investment accounts may be set to any of the following:

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both. - `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code. - `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States. - `529`: A tax-advantaged savings plan designed to help pay for education. - `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options. - `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account. - `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account. - `DIGITALASSET`: An account containing digital assets. - `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history. - `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent. - `INSTITUTIONALTRUST`: An institutional trust account. - `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement. - `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes. - `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines. - `OTHERINVESTMENT`: Use when none of the listed enums apply. - `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account. - `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement. - `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement. - `TAXABLE`: A taxable investment account. - `TDA`: TreasuryDirect Account. - `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms. - `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time. - `UGMA`: Uniform Gifts to Minors Act account. - `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFEDPLAN`, `NONQUALIFIEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts. The `accountType` field for loan accounts may be set to any of the following:

*   `AUTOLOAN`: A type of loan used to finance a car purchase. - `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time. - `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral. - `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments. - `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. - `MILITARYLOAN`: A military loan. - `MORTGAGE`: A type of loan you can use to buy or refinance a home. - `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower. - `SMBLOAN`: A small/medium business loan. - `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts. The `accountType` field for line of credit accounts may be set to any of the following:

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds. - `CHARGE`: An account to which goods and services may be charged on credit. - `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time. - `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment. - `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |
| `RESTRICTED` | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Commercial account types 

The `accountType` field for accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `COMMERCIALDEPOSIT` | A deposit account for commercial customers, for example a business trust account |
| `COMMERCIALLOAN` | A preset borrowing limit that can be used at any time |
| `COMMERCIALLINEOFCREDIT` | An account with a preset borrowing limit that can be used at any time |
| `COMMERCIALINVESTMENT` | Investment Account for Commercial Customers. e.g. Commercial Brokerage Account |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-): - `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+) - `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-) - `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`. _`AUTHORIZATION`_ `MEMO` - A pending transaction to be completed at the end of this day _`PENDING` - A pending transaction_ `POSTED` - A posted transaction  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "ATM deposit",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 38.9
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:

*   `fees` _`transactionType`_

If the transaction involves a security, Plaid additionally requires the following fields:

*   `unitPrice` _`units`_ `symbol` OR both `securityId` and `securityIdType`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-): - `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+) - `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-) - `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`. _`AUTHORIZATION`_ `MEMO` - A pending transaction to be completed at the end of this day _`PENDING` - A pending transaction_ `POSTED` - A posted transaction  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:

*   ADJUSTMENT - fee _ATM - cash_ CASH - cash _CHECK - cash_ CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum. _CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum._ CONTRIBUTION - buy (if transaction involves a security) or cash _DEP - cash_ DEPOSIT - cash _DIRECTDEBIT - cash_ DIRECTDEP - cash _DIV - cash_ DIVIDEND - cash _DIVIDENDREINVEST - buy_ EXPENSE - cash _FEE - fee_ INCOME - cash _INTEREST - cash_ INVEXPENSE - cash _JRNLFUND - transfer_ JRNLSEC - transfer _MARGININTEREST - cash_ OPTIONEXERCISE - transfer _OPTIONEXPIRATION - transfer_ OTHER - cash - (unclassified) _PAYMENT - cash_ POS - cash _PURCHASED - buy_ PURCHASEDTOCOVER - buy _PURCHASETOCLOSE - buy_ PURCHASETOOPEN - buy _REINVESTOFINCOME - buy_ REPEATPMT - cash _RETURNOFCAPITAL - cash_ SOLD - sell _SOLDTOCLOSE - sell_ SOLDTOOPEN - sell _SPLIT - transfer_ SRVCHG - fee _TRANSFER - transfer_ XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price. This field, along with `securityIdType` are **required** unless `symbol` is provided. **Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL. This field, along with `securityId` are **required** unless `symbol` is provided. **Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options. **Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Share purchase",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 428.08,
  "fees": 4.28,
  "transactionType": "PURCHASED"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-): - `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+) - `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-) - `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`. _`AUTHORIZATION`_ `MEMO` - A pending transaction to be completed at the end of this day _`PENDING` - A pending transaction_ `POSTED` - A posted transaction  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types

*   `ADJUSTMENT`: Adjustment or correction. - `FEE`: Fee charge. For example, a late payment fee. - `INTEREST`: Interest charge. - `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages). - `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time. - `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment. - `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal. - `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Monthly loan payment-minimum due",
  "debitCreditMemo": "CREDIT",
  "status": "POSTED",
  "amount": 1638.83
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-): - `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+) - `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-) - `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`. _`AUTHORIZATION`_ `MEMO` - A pending transaction to be completed at the end of this day _`PENDING` - A pending transaction_ `POSTED` - A posted transaction  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-foreignCurrency)

string

Currency, fund and precious metal codes as of Jan. 1, 2023 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html)  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`, `PURCHASE`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#LineOfCreditTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Recurring payment",
  "debitCreditMemo": "CREDIT",
  "status": "AUTHORIZATION",
  "amount": 38.9
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 6.2 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v6.2 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountidstatements) | Get account statements |
| [/accounts/{accountId}/statements/{statementId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountidstatementsstatementid) | Get account statement PDF |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |
| [/accounts/{accountId}/asset-transfer-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accountsaccountidasset-transfer-networks) | Get asset transfer networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `PRIMARY_JOINT_TENANTS`, `SECONDARY`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SECONDARY_JOINT_TENANTS`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-telephones-type)

required, string

Telephone number type  
  

Possible values: `HOME`, `BUSINESS`, `CELL`, `FAX`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Max length: `3`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-response-page-nextOffset)

string

Opaque offset identifier

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [commercialAccount](https://plaid.com#commercial-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [digitalWallet](https://plaid.com#digital-wallet-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investment account](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "accountId": "depositAccount0000001",
      "accountType": "CHECKING",
      "accountNumberDisplay": "5820",
      "productName": "Checking",
      "nickname": "Main Checking",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOAN_ACCOUNT",
      "accountId": "loanAccount0000001",
      "accountType": "LOAN",
      "accountNumberDisplay": "4704",
      "productName": "Loan",
      "nickname": "Primary Loan",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOC_ACCOUNT",
      "accountId": "locAccount0000001",
      "accountType": "LINEOFCREDIT",
      "accountNumberDisplay": "8200",
      "productName": "Line of Credit",
      "nickname": "First plaidypus LOC",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "INVESTMENT_ACCOUNT",
      "accountId": "investmentAccount0000001",
      "accountType": "TAXABLE",
      "accountNumberDisplay": "1050",
      "productName": "Brokerage Account",
      "nickname": "First plaidypus Brokerage",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

#### Search for statements 

Get account statements.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements?startTime=2022-04-01&endTime=2022-04-30' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-page-nextOffset)

string

Opaque offset identifier

[statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements)

required, \[object\]

An array of statements, each with its own HATEOAS link to retrieve the account statement

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-accountId)

string

Corresponds to `accountId` in Account entity  
  

Max length: `256`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-statementId)

string

Long-term persistent identity of the statement. This identity must be unique within your organization  
  

Max length: `256`

[statementDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-statementDate)

string

The date the statement becomes available to be viewed by the user  
  

Format: `date`

Max length: `10`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-description)

string

Description of the statement

[links](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-links)

\[object\]

The HATEOAS links to retrieve this account statement, or to invoke other APIs.  
**Note:** Plaid only accepts one link object in this array

[href](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-links-href)

required, string

The resource URL  
  

Format: `uri-reference`

[action](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-links-action)

string

The HTTP method to use for the request  
  

Possible values: `GET`, `POST`, `PATCH`, `DELETE`, `PUT`

[rel](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-links-rel)

string

The relation of this link to its containing entity, as defined by the [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)

[types](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-links-types)

\[string\]

The content-types that can be used in the Accept header. **Note:** Plaid currently only accepts the PDF (`application/pdf`) content type  
  

Possible values: `application/pdf`, `image/gif`, `image/jpeg`, `image/tiff`, `image/png`, `application/json`

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-response-statements-status)

string

Availability status of statement

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "total": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "links": [
        {
          "href": "/accounts/1111/statements?offSet=2&limit=10"
        }
      ]
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

#### Get account statement 

Get account statement PDF

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-{statementid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-statements-{statementid}-request-statementId)

string

Statement identifier, found in the `GET /accounts/{accountId}/statements` endpoint response  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements/{statementId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return a raw binary PDF statement file.

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp`  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque offset identifier

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "CHECK",
      "checkNumber": 1234,
      "payee": "ACME LLC",
      "transactionId": "depositTransaction000000001",
      "postedTimestamp": "2022-04-06T00:00:00.000Z",
      "transactionTimestamp": "2022-04-05T00:00:00.000Z",
      "description": "check for latest ACME invoice",
      "debitCreditMemo": "DEBIT",
      "status": "PENDING",
      "amount": 400
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "ADJUSTMENT",
      "transactionId": "depositTransaction000000002",
      "postedTimestamp": "2022-04-07T00:00:00.000Z",
      "transactionTimestamp": "2022-04-07T00:00:00.000Z",
      "description": "reconciliation/adjustment of bank statement error",
      "debitCreditMemo": "DEBIT",
      "status": "POSTED",
      "amount": 0.8
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "ATMDEPOSIT",
      "transactionId": "depositTransaction000000003",
      "postedTimestamp": "2022-04-08T00:00:00.000Z",
      "transactionTimestamp": "2022-04-08T00:00:00.000Z",
      "description": "ATM cash deposit location #1234",
      "debitCreditMemo": "CREDIT",
      "status": "POSTED",
      "amount": 101.8
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque offset identifier

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System
*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   US\_FEDNOW: Federal Reserve Instant Payment System
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_RTP: US Real Time Payments System

  
  

Possible values: `CA_ACSS`, `CA_LVTS`, `US_ACH`, `US_CHIPS`, `US_FEDNOW`, `US_FEDWIRE`, `US_RTP`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/asset-transfer-networks 

#### Get asset transfer details for this account 

Get asset transfer networks supported by an account. For example, Automated Customer Account Transfer Service (ACATS). For more information about how Plaid uses this information, see the [Plaid Investments Move API](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-request-offset)

string

An opaque ID that indicates there is at least one more page of data available. This value does not need to be numeric or have any specific pattern. If provided, Plaid will use this value to send a new request and retrieve the next page. Omitting this value indicates that there is no more data to retrieve.

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/asset-transfer-networks?limit=25' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[assetTransferNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks)

required, \[object\]

A paginated array of asset transfer networks for the account

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifier)

required, string

The number used to identify the account within the asset transfer network. If identifierType is ACCOUNT_NUMBER, this is the account number; if identifierType is TOKENIZED_ACCOUNT_NUMBER, this is a tokenized account number_

[identifierType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifierType)

string

The type of identifier used to identify the account in the payment network  
  

Possible values: `ACCOUNT_NUMBER`, `TOKENIZED_ACCOUNT_NUMBER`

[institutionName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionName)

string

The name of the institution holding the account

[institutionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionId)

required, string

Institution identifier used by the asset transfer network ie. the Depository Trust and Clearing Corporation code for the institution holding the account

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-type)

required, string

The type of asset transfer  
  

Possible values: `CA_ATON`, `US_ACATS`, `US_DTC`

[jointAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-jointAccount)

boolean

Whether this account has joint owners

```json
{
  "assetTransferNetworks": [
    {
      "identifier": "23348817826",
      "identifierType": "ACCOUNT_NUMBER",
      "institutionName": "First Plaidypus Bank",
      "institutionId": "FPB",
      "type": "US_ACATS",
      "jointAccount": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following account types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFIEDPLAN`, `NONQUALIFEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `PREPAID`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityIds](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-securityIds)

\[object\]

Array of security identifiers

[id](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-securityIds-id)

string

Value for a unique identifier  
  

Max length: `256`

[idType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-securityIds-idType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-minimumPaymentAmount)

number

Minimum payment amount, which is due at the date specified in `nextPaymentDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-lastStmtBalance)

number

Last statement balance

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `ANNUITY_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "ANNUITY_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Commercial account descriptor 

A commercial account. For example, a business deposit account. The `accountType` field for commercial accounts may be set to any of the [account types](https://plaid.com#commercial-account-types) listed below

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `COMMERCIAL_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#CommercialAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `COMMERCIALDEPOSIT`, `COMMERCIALINVESTMENT`, `COMMERCIALLOAN`, `COMMERCIALLINEOFCREDIT`

```json
{
  "accountCategory": "COMMERCIAL_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "COMMERCIALLOAN"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `OTHERDEPOSIT`

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INSURANCE_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountCategory": "INSURANCE_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFIEDPLAN`, `NONQUALIFEDPLAN`, `OTHERINVESTMENT`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `PREPAID`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `ROLLOVER`, `ROTH`, `SARSEP`, `SPECIFIEDPENSIONPLAN`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |
| `RESTRICTED` | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Commercial account types 

The `accountType` field for accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `COMMERCIALDEPOSIT` | A deposit account for commercial customers, for example a business trust account |
| `COMMERCIALLOAN` | A preset borrowing limit that can be used at any time |
| `COMMERCIALLINEOFCREDIT` | An account with a preset borrowing limit that can be used at any time |
| `COMMERCIALINVESTMENT` | Investment Account for Commercial Customers. e.g. Commercial Brokerage Account |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-payee)

string

Payee name  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "ATM deposit",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 38.9
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Share purchase",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 428.08,
  "fees": 4.28,
  "transactionType": "PURCHASED"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  

*   `ADJUSTMENT`: Adjustment or correction.
*   `FEE`: Fee charge. For example, a late payment fee.
*   `INTEREST`: Interest charge.
*   `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages).
*   `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time.
*   `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment.
*   `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal.
*   `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Monthly loan payment-minimum due",
  "debitCreditMemo": "CREDIT",
  "status": "POSTED",
  "amount": 1638.83
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`, `PURCHASE`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md#LineOfCreditTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Recurring payment",
  "debitCreditMemo": "CREDIT",
  "status": "AUTHORIZATION",
  "amount": 38.9
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# 6.3 - Plaid Core Exchange API Reference | Plaid Docs

Core Exchange v6.3 API Reference 
=================================

#### Plaid Core Exchange API Reference 

### Overview 

When your organization builds Core Exchange, you implement a Financial Data Exchange (FDX)-aligned API. This API handles GET HTTP requests that the Plaid network (or other data networks that you partner with) send. These requests are for information about your customers' financial accounts. Please note that this specification is subject to change as we make improvements to the product. If you have questions, please reach out to the [Plaid team](https://plaid.commailto:dataconnectivity@plaid.com) .

\=\*=\*=\*=

#### Endpoints 

This specification contains the following endpoints:

| Endpoints |  |
| --- | --- |
| [/customers/current](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#customerscurrent) | Get the ID of the customer within the authorization scope |
| [/accounts/{accountId}/contact](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountidcontact) | Get account contact information |
| [/accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts) | Search and view customer accounts |
| [/accounts/{accountId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountid) | Get account balances, liabilities, and other information |
| [/accounts/{accountId}/statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountidstatements) | Get account statements |
| [/accounts/{accountId}/statements/{statementId}](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountidstatementsstatementid) | Get account statement PDF |
| [/accounts/{accountId}/transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountidtransactions) | List all account transactions |
| [/accounts/{accountId}/payment-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountidpayment-networks) | Get payment networks supported by an account |
| [/accounts/{accountId}/asset-transfer-networks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accountsaccountidasset-transfer-networks) | Get asset transfer networks supported by an account |

\=\*=\*=\*=

#### Plaid integration and interoperability 

The Core Exchange specifications describe the subset of FDX endpoints required by Plaid, as well as the subset of FDX information Plaid consumes from each endpoint. Plaid takes the following approach to documenting these subsets:

*   **ENUMS**: In cases where an endpoint describes FDX enums that Plaid doesn't consume, the specifications note the enums Plaid consumes, but refrains from removing unused enums. This enables your organization to more easily integrate your Core Exchange implementation with other data networks. For example, FDX defines many account type enums, so the specifications retain these enums but notes which account type enums Plaid consumes in the `GET \accounts\{id}` endpoint reference.
    
*   **SCHEMAS**: In cases where an endpoint describes FDX schemas that Plaid doesn't consume, the specification _omits_ the schema.
    

\=\*=\*=\*=

#### FDX compliance 

The Core Exchange API specifications are a subset of the Financial Data Exchange (FDX) API specification, the usage thereof (or any part thereof) constitutes acceptance of the FDX API License Agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The FDX API specification is distributed exclusively by FDX. Modifications to eliminate required or conditional elements prescribed in the FDX API Certification Use Cases will render any implementations using said modifications non-conformant with the FDX API Certification Use Cases. Please note that building the FDX-compliant Core Exchange API and permitting Plaid to call your build constitutes acceptance of the FDX end user license agreement, which can be found at [https://financialdataexchange.org/](https://financialdataexchange.org/) . The full FDX API standard specification is distributed exclusively by FDX.

\=\*=\*=\*=

#### Download the specification 

To view this specification and documentation as an OpenAPI YAML file, see [the public Core Exchange Github repository](https://github.com/plaid/core-exchange/tree/main/versions) .

\=\*=\*=\*=

#### Errors 

##### Error responses 

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account. Error responses must contain a `code` and `message`, and may optionally include a `debugMessage`. See the descriptions below:

*   `code`: The FDX error code: A long-term persistent identifier which can be used to trace error condition back to log information. (**Note:** This code may differ from the HTTP status code.)
*   `message`: End user displayable information which might help the customer diagnose an error
*   `debugMessage`: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use

##### Example error 

The following is an example response with an HTTP status code of 409.

```json
{
  "code": 705,
  "message": "Account is closed",
  "debugMessage": "Operation is not supported by the closed account"
}
```

See the Errors table in each endpoint description for more specific message and debug message examples.

### Endpoints 

\=\*=\*=\*=

#### /customers/current 

#### Get current authenticated customer ID 

Get the ID of the customer within the authorization scope. If you use [OIDC authentication](https://plaid.comhttps://plaid.com/core-exchange/docs/authentication/index.html.md#create-an-oidc-compliant-server) (recommended) you _do not_ need to implement this endpoint. Plaid will identify the customer using the OIDC [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) . If you use OAuth2 authentication, Plaid will use this endpoint as an alternate method of customer identification.

**Request fields**

This endpoint takes an empty request body.

```json
curl -X GET 'https://api.your-org.com/fdx/v5/customers/current' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[customerId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#customers-current-response-customerId)

required, string

Long-term persistent identity of the customer. This identity must be unique within your organization. Plaid consumes this customer ID if your organization uses OAuth2 instead of OIDC to secure the API. Plaid expects your organization to issue the ID as a consistent, static, opaque, unique identifier for the user  
  

Max length: `256`

```json
{
  "customerId": "someLongTermUniqueIDString"
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/contact 

#### Get an account's contact information 

Get contact information on the account.  
Plaid links contact information to accounts, rather than to users. Plaid consumes multiple holders and their contact information for the account, but doesn't attempt to correlate holders to their respective contact information. For more information about Plaid's identity model, see [Plaid Identity API](https://plaid.com/docs/api/products/identity/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-contact-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/contact' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

Details used to verify an account

**Properties**

[holders](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders)

required, \[object\]

Owners of the account. Note that while the [FDX specification](https://financialdataexchange.org) enables associating holders and their contact information in the full `AccountHolder` schema, Plaid doesn't consume these associations. Instead, Plaid consumes limited information for each `AccountHolder` and doesn't associate contact information such as emails, addresses, or telephone numbers to account holders. For more information about Plaid's data model for account contact information, see [Identity](https://plaid.com/docs/api/products/identity/index.html.md)  
  

Min items: `1`

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-name)

required, object

The name of an individual in their role as a customer. Plaid expects at least one populated name field. If any field is missing (for example, no first name), then you respond with an empty string for that field

[first](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-name-first)

required, string

First name

[middle](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-name-middle)

string

Middle name

[last](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-name-last)

required, string

Last name

[suffix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-name-suffix)

string

Generational or academic suffix, e.g. Jr., Sr., III

[prefix](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-name-prefix)

string

Prefix, e.g. Mr., Mrs., Dr.

[relationship](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-holders-relationship)

string

Customer's relationship to the account  
  

Possible values: `AUTHORIZED_SIGNER`, `AUTHORIZED_USER`, `BUSINESS`, `FOR_BENEFIT_OF`, `FOR_BENEFIT_OF_PRIMARY`, `FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SECONDARY`, `FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED`, `FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED`, `POWER_OF_ATTORNEY`, `PRIMARY`, `PRIMARY_BORROWER`, `PRIMARY_JOINT`, `PRIMARY_JOINT_TENANTS`, `SECONDARY`, `SECONDARY_BORROWER`, `SECONDARY_JOINT`, `SECONDARY_JOINT_TENANTS`, `SOLE_OWNER`, `TRUSTEE`, `UNIFORM_TRANSFER_TO_MINOR`

[emails](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-emails)

required, \[string\]

Email addresses associated with the account  
  

Min items: `1`

[addresses](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses)

required, \[object\]

Physical mail addresses associated with the account  
  

Min items: `1`

[line1](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-line1)

required, string

Address line 1  
  

Max length: `64`

[line2](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-line2)

string

Address line 2  
  

Max length: `64`

[line3](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-line3)

string

Address line 3  
  

Max length: `64`

[city](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-city)

required, string

City  
  

Max length: `64`

[region](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-region)

string

State or province  
  

Max length: `64`

[postalCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-postalCode)

string

Postal code  
  

Max length: `10`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-country)

required, string

Country code  
  

Possible values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-type)

string

Type of address location. One of BUSINESS, DELIVERY, HOME, MAILING  
  

Possible values: `BUSINESS`, `DELIVERY`, `HOME`, `MAILING`

[primary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-addresses-primary)

boolean

Whether this is the primary and first address to use for contact

[telephones](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-telephones)

required, \[object\]

Telephone numbers associated with the account  
  

Min items: `1`

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-telephones-type)

required, string

Purpose of the phone number: HOME, BUSINESS, PERSONAL, FAX, or BOTH. BOTH indicates number is used for both HOME and BUSINESS purposes. `CELL` value is deprecated in v6.3, replaced as a `network` value  
  

Possible values: `BOTH`, `BUSINESS`, `CELL`, `FAX`, `HOME`, `PERSONAL`

[country](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-telephones-country)

string

Country calling codes defined by ITU-T recommendations E.123 and E.164, such as '+1' for United States and Canada, see [Listofcountrycallingcodes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)  
  

Min length: `1`

Max length: `4`

Pattern: `^\+?[1-9][0-9]{0,2}$`

[number](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-telephones-number)

required, string

Telephone subscriber number defined by ITU-T recommendation E.164  
  

Max length: `15`

Pattern: `\d+`

[network](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-telephones-network)

string

The network technology used for this telephone. One of CELLULAR, LANDLINE, PAGER, SATELLITE, or VOIP  
  

Possible values: `CELLULAR`, `LANDLINE`, `PAGER`, `SATELLITE`, `VOIP`

[primary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AccountContact-telephones-primary)

boolean

Whether this is the primary and first telephone number to call

```json
{
  "holders": [
    {
      "relationship": "SECONDARY",
      "name": {
        "first": "Ernest",
        "middle": "Miller",
        "last": "Hemingway",
        "suffix": "IV"
      }
    },
    {
      "relationship": "PRIMARY_JOINT",
      "name": {
        "first": "Maya",
        "last": "Angelou",
        "middle": "Annie"
      }
    }
  ],
  "emails": [
    "ernest.m.hemingway@domain.tld",
    "m.angelou@domain.tld"
  ],
  "addresses": [
    {
      "line1": "1850 N Clark St",
      "line2": "Apartment 103",
      "city": "Chicago",
      "region": "IL",
      "postalCode": "60614",
      "country": "US"
    },
    {
      "line1": "2014 N Main St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "telephones": [
    {
      "type": "HOME",
      "country": "1",
      "number": "3127771926"
    },
    {
      "type": "CELL",
      "country": "53",
      "number": "45915607"
    },
    {
      "type": "HOME",
      "country": "1",
      "number": "4157771926"
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts 

#### List all accounts 

Search and view customer accounts

**Request fields**

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-request-offset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

In: `query`

[pageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-request-pageKey)

string

Opaque cursor used by the provider to send the next set of records. Pagination can be implemented per provider's preference

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts?offset=15&limit=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-response-page-nextOffset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

[nextPageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-response-page-nextPageKey)

string

Opaque identifier. Does not need to be numeric or have any specific pattern. Implementation specific

[accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-response-accounts)

required, \[object\]

An optionally paginated array of account descriptors. Each account descriptor is sent as a key-value pair, with the account descriptor object as the value and the account type as the key. Accepted keys include: [annuityAccount](https://plaid.com#annuity-account-descriptor) , [commercialAccount](https://plaid.com#commercial-account-descriptor) , [depositAccount](https://plaid.com#deposit-account-descriptor) , [digitalWallet](https://plaid.com#digital-wallet-descriptor) , [investmentAccount](https://plaid.com#investment-account-descriptor) , [locAccount](https://plaid.com#line-of-credit-account-descriptor) , [loanAccount](https://plaid.com#loan-account-descriptor) , [investment account](https://plaid.com#investment-account-descriptor) , and [insuranceAccount](https://plaid.com#insurance-account-descriptor) .  
  

Min items: `1`

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "accountId": "depositAccount0000001",
      "accountType": "CHECKING",
      "accountNumberDisplay": "5820",
      "productName": "Checking",
      "nickname": "Main Checking",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOAN_ACCOUNT",
      "accountId": "loanAccount0000001",
      "accountType": "LOAN",
      "accountNumberDisplay": "4704",
      "productName": "Loan",
      "nickname": "Primary Loan",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOC_ACCOUNT",
      "accountId": "locAccount0000001",
      "accountType": "LINEOFCREDIT",
      "accountNumberDisplay": "8200",
      "productName": "Line of Credit",
      "nickname": "First plaidypus LOC",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "INVESTMENT_ACCOUNT",
      "accountId": "investmentAccount0000001",
      "accountType": "TAXABLE",
      "accountNumberDisplay": "1050",
      "productName": "Brokerage Account",
      "nickname": "First plaidypus Brokerage",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId} 

#### Get detailed information for a specific account 

Get account balances, liabilities, and other information. Plaid uses this endpoint to get balances for [deposit accounts](https://plaid.com#deposit-account) , get liabilities for `STUDENTLOAN`, `MORTGAGE`, and `CREDITCARD` [loan accounts](https://plaid.com#loan-account) , and get balances and holdings for investment accounts for [investment accounts](https://plaid.com#investment-account) . See [Plaid Balance API](https://plaid.com/docs/api/products/balance/index.html.md) , [Plaid Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) , and [Plaid Investments API](https://plaid.com/docs/investments/index.html.md) for more information on how Plaid uses this information. **Info**: Plaid does not use `/accounts/{accountId}` for annuity accounts, commercial accounts, or insurance accounts. However, these accounts are still included in the `/accounts` list, so that they are discoverable by users.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return one of the following type of [accounts](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#accounts) :

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#investment-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#line-of-credit-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md#loan-account)

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `HIGHINTERESTSAVINGSACCOUNT`, `FIRSTHOMESAVINGSACCOUNT`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements 

#### Search for statements 

Get account statements.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-offset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

In: `query`

[pageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-pageKey)

string

Opaque cursor used by the provider to send the next set of records. Pagination can be implemented per provider's preference

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp` Will support filtering by time in a future major release. To support filtering by date only, see StartDateQuery  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp` Will support filtering by time in a future major release. To support filtering by date only, see EndDateQuery  
  

Format: `date`

Max length: `10`

In: `query`

[startDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-startDate)

string

Start date for use in retrieval of elements (ISO 8601 format). Provider to define the date ranges and behaviors they will support. Example of defined behavior: - Recipients need to either specify both start date and end date or neither.

If both start date and end date are not specified; default provided.
Default range: 7 Days of past data. (Today's date - 6 days both dates are inclusive)

\- Recipient can specify the same start date and end date.

The returned data will reflect transactions from that date

\- If start date and end date both are specified and if start date is later than end date,

return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

\- If start Date and end date both are specified and if start date is older than what the Data Provider supports,

then the Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec.
Example: If today is 5/14/2024 and the DP supports 24 months, the start date should be 5/14/2022 and newer;
it should not be 5/13/2022 or older

\- If start date is specified but end date is not specified or vice versa;

Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

  
  

Format: `date`

Max length: `10`

In: `query`

[endDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-request-endDate)

string

End date for use in retrieval of elements (ISO 8601 format). Provider to define the date ranges and behaviors they will support. Example of defined behavior: - Recipients need to either specify both start date and end date or neither.

If both start date and end date are not specified; default provided.
Default range: 7 Days of past data. (Today's date - 6 days both dates are inclusive)

\- Recipient can specify the same start date and end date. The returned data will reflect transactions from that date - If start date and end date both are specified and if start date is later than end date,

return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

\- If start Date and end date both are specified and if start date is older than what the Data Provider supports,

then the Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec.
Example: If today is 5/14/2024 and the DP supports 24 months, the start date should be 5/14/2022 and newer;
it should not be 5/13/2022 or older

\- If start date is specified but end date is not specified or vice versa;

Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

\- If end date is today's date, the most recent transactions from the time the request is received will be returned  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements?startTime=2022-04-01&endTime=2022-04-30' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-page-nextOffset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

[nextPageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-page-nextPageKey)

string

Opaque identifier. Does not need to be numeric or have any specific pattern. Implementation specific

[statements](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements)

required, \[object\]

An array of statements, each with its own HATEOAS link to retrieve the account statement

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-accountId)

string

Corresponds to `accountId` in Account entity  
  

Max length: `256`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-statementId)

string

Long-term persistent identity of the statement. This identity must be unique within your organization  
  

Max length: `256`

[statementDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-statementDate)

string

The date the statement becomes available to be viewed by the user  
  

Format: `date`

Max length: `10`

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-description)

string

Description of the statement

[links](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-links)

\[object\]

The HATEOAS links to retrieve this account statement, or to invoke other APIs.  
**Note:** Plaid only accepts one link object in this array

[href](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-links-href)

required, string

The resource URL  
  

Format: `uri-reference`

[action](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-links-action)

string

The HTTP method to use for the request  
  

Possible values: `GET`, `POST`, `PATCH`, `DELETE`, `PUT`

[rel](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-links-rel)

string

The relation of this link to its containing entity, as defined by the [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)

[types](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-links-types)

\[string\]

The content-types that can be used in the Accept header. **Note:** Plaid currently only accepts the PDF (`application/pdf`) content type  
  

Possible values: `application/pdf`, `image/gif`, `image/jpeg`, `image/tiff`, `image/png`, `application/json`

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-response-statements-status)

string

Availability status of statement

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "total": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "links": [
        {
          "href": "/accounts/1111/statements?offSet=2&limit=10"
        }
      ]
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/statements/{statementId} 

#### Get account statement 

Get account statement PDF

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-{statementid}-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[statementId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-statements-{statementid}-request-statementId)

string

Statement identifier, found in the `GET /accounts/{accountId}/statements` endpoint response  
  

Max length: `256`

In: `path`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/statements/{statementId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

A 200 response will return a raw binary PDF statement file.

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 601 | Customer not found | A customer with the provided customer ID could not be found |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/transactions 

#### Search for account transactions 

List all account transactions. Plaid always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`, and expects the time filters to be based on the `postedTimestamp`.  
Plaid consumes data from this endpoint only for [loan](https://plaid.com#loan-account) , [investment](https://plaid.com#investment-account) , [deposit](https://plaid.com#deposit-account) , and [line of credit](https://plaid.com#line-of-credit-account) accounts.

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-offset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

In: `query`

[pageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-pageKey)

string

Opaque cursor used by the provider to send the next set of records. Pagination can be implemented per provider's preference

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

[startTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-startTime)

string

Start time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp` Will support filtering by time in a future major release. To support filtering by date only, see StartDateQuery  
  

Format: `date`

Max length: `10`

In: `query`

[endTime](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-endTime)

string

End time for use in retrieval of elements (ISO 8601). For transactions, Plaid expects this to filter by the `postedTimestamp` Will support filtering by time in a future major release. To support filtering by date only, see EndDateQuery  
  

Format: `date`

Max length: `10`

In: `query`

[startDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-startDate)

string

Start date for use in retrieval of elements (ISO 8601 format). Provider to define the date ranges and behaviors they will support. Example of defined behavior: - Recipients need to either specify both start date and end date or neither.

If both start date and end date are not specified; default provided.
Default range: 7 Days of past data. (Today's date - 6 days both dates are inclusive)

\- Recipient can specify the same start date and end date.

The returned data will reflect transactions from that date

\- If start date and end date both are specified and if start date is later than end date,

return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

\- If start Date and end date both are specified and if start date is older than what the Data Provider supports,

then the Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec.
Example: If today is 5/14/2024 and the DP supports 24 months, the start date should be 5/14/2022 and newer;
it should not be 5/13/2022 or older

\- If start date is specified but end date is not specified or vice versa;

Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

  
  

Format: `date`

Max length: `10`

In: `query`

[endDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-request-endDate)

string

End date for use in retrieval of elements (ISO 8601 format). Provider to define the date ranges and behaviors they will support. Example of defined behavior: - Recipients need to either specify both start date and end date or neither.

If both start date and end date are not specified; default provided.
Default range: 7 Days of past data. (Today's date - 6 days both dates are inclusive)

\- Recipient can specify the same start date and end date. The returned data will reflect transactions from that date - If start date and end date both are specified and if start date is later than end date,

return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

\- If start Date and end date both are specified and if start date is older than what the Data Provider supports,

then the Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec.
Example: If today is 5/14/2024 and the DP supports 24 months, the start date should be 5/14/2022 and newer;
it should not be 5/13/2022 or older

\- If start date is specified but end date is not specified or vice versa;

Data Provider should return 'invalid date range' error code: 703, HTTPS 400 per the FDX spec

\- If end date is today's date, the most recent transactions from the time the request is received will be returned  
  

Format: `date`

Max length: `10`

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/transactions?startTime2022-11-01&limit=100' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-response-page-nextOffset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

[nextPageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-response-page-nextPageKey)

string

Opaque identifier. Does not need to be numeric or have any specific pattern. Implementation specific

[transactions](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-transactions-response-transactions)

required, array

An optionally paginated array of transactions. May be any of the following: [deposit transaction](https://plaid.com#deposit-transaction) , [investment transaction](https://plaid.com#investment-transaction) , [loan transaction](https://plaid.com#loan-transaction) , [line of credit transaction](https://plaid.com#line-of-credit-transaction)

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "CHECK",
      "checkNumber": 1234,
      "payee": "ACME LLC",
      "transactionId": "depositTransaction000000001",
      "postedTimestamp": "2022-04-06T00:00:00.000Z",
      "transactionTimestamp": "2022-04-05T00:00:00.000Z",
      "description": "check for latest ACME invoice",
      "debitCreditMemo": "DEBIT",
      "status": "PENDING",
      "amount": 400
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "ADJUSTMENT",
      "transactionId": "depositTransaction000000002",
      "postedTimestamp": "2022-04-07T00:00:00.000Z",
      "transactionTimestamp": "2022-04-07T00:00:00.000Z",
      "description": "reconciliation/adjustment of bank statement error",
      "debitCreditMemo": "DEBIT",
      "status": "POSTED",
      "amount": 0.8
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "ATMDEPOSIT",
      "transactionId": "depositTransaction000000003",
      "postedTimestamp": "2022-04-08T00:00:00.000Z",
      "transactionTimestamp": "2022-04-08T00:00:00.000Z",
      "description": "ATM cash deposit location #1234",
      "debitCreditMemo": "CREDIT",
      "status": "POSTED",
      "amount": 101.8
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 422 | 704 | Account type not supported | The account type does not support the selected action |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/payment-networks 

#### Get payment networks supported by the account 

Get payment networks supported by an account, for example ACH (Automated Clearing House). For more information about how Plaid uses this information, see the [Plaid Auth API](https://plaid.com/docs/api/products/auth/index.html.md) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-request-offset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

In: `query`

[pageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-request-pageKey)

string

Opaque cursor used by the provider to send the next set of records. Pagination can be implemented per provider's preference

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/payment-networks?offset=50' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[page](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-page)

object

Contains the opaque identifier, `nextOffset`, to indicate a paginated result set.

[nextOffset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-page-nextOffset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

[nextPageKey](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-page-nextPageKey)

string

Opaque identifier. Does not need to be numeric or have any specific pattern. Implementation specific

[paymentNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks)

required, \[object\]

Array of payment networks. Not all deposit accounts support ACH transfers. For example, a prepaid debit card account doesn't support ACH  
  

Min items: `1`

[bankId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-bankId)

required, string

Bank identifier used by the payment network. Typically the 9-digit routing transit number (RTN) associated with the account number at a US institution, or the 3-digit Institution (FID) and 5-digit Transit numbers for Canadian institutions, including leading zeroes

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-identifier)

required, string

The number used to identify the account within the payment network.

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-type)

required, string

Suggested values for Payment Network Type. `US_` refers to the USA, and `CA_` refers to Canada. Possible values:  

*   CA\_ACSS: Automated Clearing House Settlement System
*   CA\_LVTS: Large-Value Transfer System
*   US\_ACH: Automated Clearing House, also called Fed ACH network (mostly small banks)
*   US\_CHIPS: Clearinghouse Interbank Payments System. Also called Clearing House ACH network (primarily big banks)
*   US\_FEDNOW: Federal Reserve Instant Payment System
*   US\_FEDWIRE: Fedwire Funds Service
*   US\_RTP: US Real Time Payments System

  
  

Possible values: `CA_ACSS`, `CA_LVTS`, `US_ACH`, `US_CHIPS`, `US_FEDNOW`, `US_FEDWIRE`, `US_RTP`

[transferIn](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferIn)

required, boolean

Can transfer funds to the account using this information. Plaid expect that this value represents the account's current ability to be credited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

[transferOut](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-payment-networks-response-paymentNetworks-transferOut)

required, boolean

Can transfer funds from the account using this information. Plaid expect that this value represents the account's current ability to be debited through a payment network. Plaid recommends dynamically updating this value, for example to represent if the account is locked or not.  
**Note:** Both `transferIn` and `transferOut` must be `true` in order for the account to support ACH

```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

\=\*=\*=\*=

#### /accounts/{accountId}/asset-transfer-networks 

#### Get asset transfer details for this account 

Get asset transfer networks supported by an account. For example, Automated Customer Account Transfer Service (ACATS). For more information about how Plaid uses this information, see the [Plaid Investments Move API](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) .

**Request fields**

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-request-accountId)

string

Account identifier, found in the `GET /accounts` endpoint response. Plaid expects the ID to be a different value from the account number  
**Note:** If the status of the `accountId` provided is `RESTRICTED`, you can send a 200 response with an empty body to indicate that no payment networks are available at this time.  
  

Max length: `256`

In: `path`

[offset](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-request-offset)

string

Opaque cursor used by the provider to send the next set of records. Deprecated in favor of PageKeyQuery, will be removed with a future major release

In: `query`

[limit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-request-limit)

integer

The number of elements that the API consumer wishes to receive. Plaid has a default limit of 100 elements. If your organization has a different limit, use the lower limit to determine how many items to send per page. To retrieve multiple pages, Plaid will use the opaque `nextOffset` field to send a subsequent request until the `nextOffset` is no longer included.

In: `query`

```json
curl -X GET 'https://api.your-org.com/fdx/v5/accounts/{accountId}/asset-transfer-networks?limit=25' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '
```

###### 200 OK 

**Response fields** and example

[assetTransferNetworks](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks)

required, \[object\]

A paginated array of asset transfer networks for the account

[identifier](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifier)

required, string

The number used to identify the account within the asset transfer network. If identifierType is ACCOUNT_NUMBER, this is the account number; if identifierType is TOKENIZED_ACCOUNT_NUMBER, this is a tokenized account number_

[identifierType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-identifierType)

string

The type of identifier used to identify the account in the payment network  
  

Possible values: `ACCOUNT_NUMBER`, `TOKENIZED_ACCOUNT_NUMBER`

[institutionName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionName)

string

The name of the institution holding the account

[institutionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-institutionId)

required, string

Institution identifier used by the asset transfer network ie. the Depository Trust and Clearing Corporation code for the institution holding the account

[type](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-type)

required, string

The type of asset transfer  
  

Possible values: `CA_ATON`, `US_ACATS`, `US_DTC`

[jointAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#accounts-{accountid}-asset-transfer-networks-response-assetTransferNetworks-jointAccount)

boolean

Whether this account has joint owners

```json
{
  "assetTransferNetworks": [
    {
      "identifier": "23348817826",
      "identifierType": "ACCOUNT_NUMBER",
      "institutionName": "First Plaidypus Bank",
      "institutionId": "FPB",
      "type": "US_ACATS",
      "jointAccount": true
    }
  ]
}
```

###### Error responses 

| HTTP status code | FDX error code | Example message | Example debug message |
| --- | --- | --- | --- |
| 401 | 602 | Customer not authorized | Authenticated customer does not have the authorization to perform this action |
| 404 | 701 | Account not found | An account with the provided account ID could not be found |
| 409 | 705 | Account is closed | Operation is not supported by the closed account |
| 500 | 500 | Internal server error | Provider custom developer-level error details for troubleshooting |
| 500 | 501 | Subsystem unavailable | A system required to process the request was not available. Request was not processed |
| 503 | 503 | Scheduled maintenance | System is down for maintenance. Retry-After HTTP header may be used to communicate estimated time of recovery |

### Data definitions 

\=\*=\*=\*=

#### Accounts 

Account objects contain full details of each account type. (**Note:** Account objects differ from [account descriptors](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#account-descriptors) , which are lightweight objects that contain minimally necessary account details.) The Core Exchange API supports the following account types:

*   [Deposit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#deposit-account)
*   [Investment account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#investment-account)
*   [Loan account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#loan-account)
*   [Line of credit account](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#line-of-credit-account)

##### Deposit account 

Full details of a deposit account. Plaid consumes the same information for all types of deposit accounts. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`.  
The `accountType` field for deposit accounts may be set to any of the [account types](https://plaid.com#deposit-account-types) listed below.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `HIGHINTERESTSAVINGSACCOUNT`, `FIRSTHOMESAVINGSACCOUNT`, `OTHERDEPOSIT`

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-currentBalance)

required, number

The total amount of money in the account (sum of all posted/cleared transactions, not including pending transactions). For Plaid's full definition, see the [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-current)

[availableBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccount-availableBalance)

required, number

The money in the account available to spend (sum of all transactions, plus or minus pending transactions). For Plaid's full definition, see [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-accounts-balances-available)

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS",
  "currentBalance": 1399.02,
  "availableBalance": 1399.02
}
```

##### Investment account 

Full details of an investment account. Plaid consumes all `InvestmentAccount` FDX fields for all types of investment accounts. In the holdings array, Plaid consumes fields depending on their relevancy to the holding type. See the `holdings` array for more information. Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFIEDPLAN`, `NONQUALIFEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `PREPAID`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `SPECIFIEDPENSIONPLAN`, `SARSEP`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

[availableCashBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-availableCashBalance)

required, number

Cash balance across all sub-accounts. Plaid expects that this includes sweep funds

[balanceAsOf](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-balanceAsOf)

string

Date and time of the balance  
ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[currentValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-currentValue)

required, number

Total current value of all investments

[holdings](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings)

\[object\]

Holdings in the investment account. Plaid maps the `holding` and the `investmentAccount` FDX models to its securities models, which hold universal information like the ticker symbol, and to its holdings models, which hold account-specific information like balances. For more information, see [Plaid investments](https://plaid.com/docs/investments/index.html.md#securities-and-holdings)

[securityIds](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-securityIds)

\[object\]

Array of security identifiers

[id](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-securityIds-id)

string

Value for a unique identifier  
  

Max length: `256`

[idType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-securityIds-idType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[holdingName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-holdingName)

string

Holding name or security name

[holdingType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-holdingType)

string

Plaid maps the holding type to the Plaid [security type](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-type) . Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `ANNUITY`, `BOND`, `CD`, `DIGITALASSET`, `MUTUALFUND`, `OPTION`, `OTHER`, `STOCK`

[holdingSubType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-holdingSubType)

string

The subtype of an investment holding. Plaid expects you to return `OTHER` and set the `holdingSubType` to indicate cash-type holdings (CASH, MONEYMARKET).  
  

Possible values: `CASH`, `MONEYMARKET`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[purchasedPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-purchasedPrice)

number

Price of holding at the time of purchase. Plaid determines an approximate [cost basis](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-cost-basis) using the purchase price and the number of units. Plaid cannot take fees into account to determine the cost basis because the FDX holding schema doesn't include fees.

[currentUnitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-currentUnitPrice)

number

Current unit price. Plaid uses this as the [institutionprice](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-holdings-institution-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-close-price) if you don't return `securityId` for holdings involving securities.

[currentUnitPriceDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-currentUnitPriceDate)

string

Current unit price as of date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[marketValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-marketValue)

required, number

Market value at the time of data retrieved

[faceValue](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-faceValue)

number

Required for bonds. Face value at the time of data retrieved. If this isn't present, Plaid assumes the holding isn't a bond and falls back to `marketValue`.

[cashAccount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-cashAccount)

required, boolean

If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account. If you don't set a value for `isCashEquivalent` in the `fiAttributes` array, then Plaid uses `cashAccount` in determining the [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) status.

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-currency)

object

Currency information if it is different from Account entity

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`. If you return a value for `isCashEquivalent`, then return the same value for `cashAccount` as a boolean.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccount-holdings-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH",
  "availableCashBalance": 3209.54,
  "balanceAsOf": "2021-07-15T14:46:41.375Z",
  "currentValue": 34938.2
}
```

##### Loan account 

Full details of a loan account. The `accountType` field for loan accounts may be set to any of the [account types](https://plaid.com#loan-account-types) listed below.  
Plaid only consumes the `MORTGAGE` and `STUDENTLOAN` types for its [Liabilities API](https://plaid.com/docs/api/products/liabilities/index.html.md) . For other loan account types Plaid consumes account details and transactions. Plaid consumes all loan account information as returned in the `GET /accounts` endpoint, as well as the additional information listed below:  
Required for all loan accounts:

*   `principalBalance`
*   `interestRate`
*   `interestRateType`

  
Optional fields for `STUDENTLOAN` accounts:

*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `maturityDate`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Required for `MORTGAGE` accounts:

*   `accountNumber`

  
Optional fields for `MORTGAGE` accounts:

*   `escrowBalance`
*   `interestPaidYearToDate`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `loanTerm`
*   `maturityDate`
*   `nextPaymentAmount`
*   `nextPaymentDate`
*   `originalPrincipal`
*   `originatingDate`

  
Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"escrowBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

[accountNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-accountNumber)

string

Full account number for the end user's handle for the account at the owning institution  
Required for accountType 'MORTGAGE'

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-principalBalance)

required, number

Principal balance

[escrowBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-escrowBalance)

number

Escrow balance of loan

[originalPrincipal](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-originalPrincipal)

number

Original principal of loan

[originatingDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-originatingDate)

string

Date loan originated  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[loanTerm](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-loanTerm)

integer

Term of loan in months

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[maturityDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-maturityDate)

string

Maturity date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[interestPaidYearToDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-interestPaidYearToDate)

number

Interest paid year to date

[interestRate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-interestRate)

required, number

The interest rate for the account, expressed as a number between 0 and 100. For example, `4` represents 4.00%, and `7.99` represents 7.99%.

[interestRateType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-interestRateType)

required, string

Specifies whether an interest rate is fixed or variable. This information is helpful for personal financial planning and advising. For example, it affects the potential benefits of refinancing, and informs whether a mortgage payment is expected to change in the future  
  

Possible values: `FIXED`, `VARIABLE`

[currentSchool](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-currentSchool)

string

Current school the student loan is connected to

[loanProviderName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccount-loanProviderName)

string

Name of the institution providing the loan

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN",
  "accountNumber": "loanAccount0000001",
  "principalBalance": 580303.95,
  "escrowBalance": 3400.61,
  "originalPrincipal": 650400,
  "originatingDate": "2021-07-15",
  "loanTerm": 360,
  "nextPaymentAmount": 2483.12,
  "nextPaymentDate": "2021-07-15",
  "lastPaymentAmount": 2483.12,
  "lastPaymentDate": "2021-07-15",
  "maturityDate": "2021-07-15",
  "interestRate": 6.99
}
```

##### Line of credit account 

Full details of a line of credit account. The `accountType` field for line of credit accounts may be set to any of the [account types](https://plaid.com#line-of-credit-account-types) listed below.  
Plaid may consume all the parameters returned by the `GET /accounts` endpoint:  

*   `availableCredit`
*   `creditLine`
*   `currentBalance`

  
Additionally, for the `CREDITCARD` accountType, Plaid consumes the previous information plus the following for its liabilities product:  

*   `advancesApr`
*   `lastPaymentAmount`
*   `lastPaymentDate`
*   `lastStmtBalance`
*   `lastStmtDate`
*   `minimumPaymentAmount`
*   `nextPaymentDate`
*   `purchasesApr`

Plaid expects a decimal amount with two places (to represent fractional values of the base currency) for all monetary amounts. For example, `"currentBalance": 192.00`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

[creditLine](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-creditLine)

number

Credit limit

[availableCredit](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-availableCredit)

number

Available credit. Required for all accountTypes except for `CHARGE`

[nextPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-nextPaymentAmount)

number

Amount of next payment. May differ from minimumPaymentAmount if the customer pays more than their minimum or out of cycle

[nextPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-nextPaymentDate)

string

Due date of next payment. May differ from statementAmountDueDate if the customer pays out of cycle ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[principalBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-principalBalance)

number

Principal balance

[currentBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-currentBalance)

required, number

Current balance of line of credit

[minimumPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-minimumPaymentAmount)

number

Minimum payment amount from last statement balance, which is due at `statementAmountDueDate`

[lastPaymentAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-lastPaymentAmount)

number

Amount of last payment

[lastPaymentDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-lastPaymentDate)

string

Last payment date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[pastDueAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-pastDueAmount)

number

Amount owed that the account holder failed to pay on the due date

[lastStmtBalance](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-lastStmtBalance)

number

Final balance amount at end of last statement

[lastStmtDate](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-lastStmtDate)

string

Last statement date  
ISO 8601 full-date in format 'YYYY-MM-DD' according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339.html#section-5.6)  
  

Format: `date`

Max length: `10`

[purchasesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-purchasesApr)

number

Annual percentage rate for purchases

[advancesApr](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccount-advancesApr)

number

Annual percentage rate for cash advances

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD",
  "nextPaymentDate": "2021-07-15",
  "currentBalance": 1722.81,
  "lastPaymentDate": "2021-07-15",
  "lastStmtDate": "2021-07-15"
}
```

\=\*=\*=\*=

#### Account descriptors 

##### Annuity account descriptor 

An annuity account. For example, a fixed or variable annuity account.  
The `accountType` field for annuity accounts may be set to any of the following:  

*   `ANNUITY`: A form of insurance or investment entitling the investor to a series of annual sums.
*   `FIXEDANNUITY`: A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account.
*   `VARIABLEANNUITY`: A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `ANNUITY_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#AnnuityAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `ANNUITY`, `FIXEDANNUITY`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "ANNUITY_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "FIXEDANNUITY"
}
```

##### Commercial account descriptor 

A commercial account. For example, a business deposit account. The `accountType` field for commercial accounts may be set to any of the [account types](https://plaid.com#commercial-account-types) listed below

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `COMMERCIAL_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#CommercialAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `COMMERCIALDEPOSIT`, `COMMERCIALINVESTMENT`, `COMMERCIALLOAN`, `COMMERCIALLINEOFCREDIT`

```json
{
  "accountCategory": "COMMERCIAL_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "COMMERCIALLOAN"
}
```

##### Deposit account descriptor 

A deposit account. For example, a checking, savings or money market account. Plaid consumes more detailed information for `CHECKING` and `SAVINGS` accounts.  
The `accountType` field for deposit accounts may be set to any of the following:  

*   `CHECKING`: A deposit account held at a financial institution that allows withdrawals and deposits.
*   `SAVINGS`: An interest-bearing deposit account held at a bank or other financial institution.
*   `CD`: A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time.
*   `COMMERCIALDEPOSIT`: A deposit account for commercial customers, for example a business trust account.
*   `ESCROW`: A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties.
*   `MONEYMARKET`: A deposit account that pays interest based on current interest rates in the money markets.
*   `OTHERDEPOSIT`: Use when none of the listed enums apply.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `CHECKING`, `SAVINGS`, `CD`, `ESCROW`, `MONEYMARKET`, `HIGHINTERESTSAVINGSACCOUNT`, `FIRSTHOMESAVINGSACCOUNT`, `OTHERDEPOSIT`

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "SAVINGS"
}
```

##### Insurance account descriptor 

An insurance account. For example, whole life insurance or short-term disability.  
The `accountType` field for insurance accounts may be set to any of the following:  

*   `LONGTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year.
*   `SHORTTERMDISABILITY`: Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year.
*   `UNIVERSALLIFE`: A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest.
*   `WHOLELIFE`: Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INSURANCE_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InsuranceAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LONGTERMDISABILITY`, `SHORTTERMDISABILITY`, `UNIVERSALLIFE`, `WHOLELIFE`

```json
{
  "accountCategory": "INSURANCE_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "WHOLELIFE"
}
```

##### Investment account descriptor 

An investment account. For example, a 401K or IRA. Plaid consumes the same details for all investment accounts.  
The `accountType` field for investment accounts may be set to any of the following:  

*   `401A`: An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both.
*   `401K`: An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code.
*   `403B`: A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States.
*   `529`: A tax-advantaged savings plan designed to help pay for education.
*   `BROKERAGEPRODUCT`: Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options.
*   `COMMERCIALINVESTMENT`: Investment Account for Commercial Customers. e.g. Commercial Brokerage Account.
*   `COVERDELL`: A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account.
*   `DIGITALASSET`: An account containing digital assets.
*   `DEFINEDBENEFIT`: An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history.
*   `GUARDIAN`: An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent.
*   `INSTITUTIONALTRUST`: An institutional trust account.
*   `IRA`: An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement.
*   `KEOGH`: A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes.
*   `NONQUALIFIEDPLAN`: A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines.
*   `OTHERINVESTMENT`: Use when none of the listed enums apply.
*   `ROLLOVER`: An account containing investments rolled over from an employee-sponsored account.
*   `ROTH`: An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement.
*   `SARSEP`: A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement.
*   `TAXABLE`: A taxable investment account.
*   `TDA`: TreasuryDirect Account.
*   `TRUST`: A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms.
*   `TERM`: Life insurance that provides coverage at a fixed rate of payments for a limited period of time.
*   `UGMA`: Uniform Gifts to Minors Act account.
*   `UTMA`: Uniform Transfers to Minors Act account.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `401A`, `401K`, `403B`, `529`, `BROKERAGEPRODUCT`, `COVERDELL`, `DIGITALASSET`, `DEFINEDBENEFIT`, `DEFERREDPROFITSHARINGPLAN`, `ESOP`, `GUARDIAN`, `INDIVIDUALPENSIONPLAN`, `INSTITUTIONALTRUST`, `INVESTMENTACCOUNT`, `IRA`, `KEOGH`, `LIFEINCOMEFUND`, `LOCKEDINRETIREMENTACCOUNT`, `LOCKEDINRETIREMENTINCOMEFUND`, `LOCKEDINRETIREMENTSAVINGSPLAN`, `NONQUALIFIEDPLAN`, `NONQUALIFEDPLAN`, `OTHERINVESTMENT`, `ROLLOVER`, `ROTH`, `PRESCRIBEDREGISTEREDRETIREMENTINCOMEFUND`, `PREPAID`, `REGISTEREDPENSIONPLAN`, `REGISTEREDDISABILITYSAVINGSPLAN`, `REGISTEREDEDUCATIONSAVINGSPLAN`, `REGISTEREDRETIREMENTINCOMEFUND`, `REGISTEREDRETIREMENTSAVINGSPLAN`, `RESTRICTEDLIFEINCOMEFUND`, `RESTRICTEDLOCKEDINSAVINGSPLAN`, `SPECIFIEDPENSIONPLAN`, `SARSEP`, `TAXABLE`, `TAXFREESAVINGSACCOUNT`, `TDA`, `TRUST`, `TERM`, `UGMA`, `UTMA`, `VARIABLEANNUITY`

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "ROTH"
}
```

##### Loan account descriptor 

A loan account. For example, mortgage, student loan or auto loan. Plaid consumes more detailed information for `MORTGAGE` and `STUDENTLOAN` accounts.  
The `accountType` field for loan accounts may be set to any of the following:  

*   `AUTOLOAN`: A type of loan used to finance a car purchase.
*   `COMMERCIALLOAN`: A preset borrowing limit that can be used at any time.
*   `HOMEEQUITYLOAN`: A type of loan in which the borrower uses the equity of his or her home as collateral.
*   `INSTALLMENT`: A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments.
*   `LOAN`: The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc.
*   `MILITARYLOAN`: A military loan.
*   `MORTGAGE`: A type of loan you can use to buy or refinance a home.
*   `PERSONALLOAN`: A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower.
*   `SMBLOAN`: A small/medium business loan.
*   `STUDENTLOAN`: A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `AUTOLOAN`, `HOMEEQUITYLOAN`, `INSTALLMENT`, `LOAN`, `MILITARYLOAN`, `MORTGAGE`, `PERSONALLOAN`, `SMBLOAN`, `STUDENTLOAN`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "HOMEEQUITYLOAN"
}
```

##### Line of credit account descriptor 

A line-of-credit account. For example, a credit card or home equity line of credit. Plaid consumes more detailed information for `CREDITCARD` accounts.  
The `accountType` field for line of credit accounts may be set to any of the following:  

*   `LINEOFCREDIT`: A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds.
*   `CHARGE`: An account to which goods and services may be charged on credit.
*   `COMMERCIALLINEOFCREDIT`: An account with a preset borrowing limit that can be used at any time.
*   `CREDITCARD`: Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment.
*   `HOMELINEOFCREDIT`: A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house.

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[accountId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-accountId)

required, string

Long-term persistent identity of the account, though not an account number. This identity must be unique within your organization.  
  

Max length: `256`

[accountNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-accountNumberDisplay)

string

Account display number for the end user's handle at the owning financial institution. Plaid expects that the last 4 digits of this masked number correspond to the last 4 digits of the account number.

[productName](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-productName)

required, string

Marketed product name for this account. Used in UIs to assist in account selection

[nickname](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-nickname)

string

Account nickname

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-status)

required, string

Account status  
  

Possible values: `CLOSED`, `DELINQUENT`, `NEGATIVECURRENTBALANCE`, `OPEN`, `PAID`, `PENDINGCLOSE`, `PENDINGOPEN`, `RESTRICTED`

[currency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-currency)

required, object

ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)

[currencyCode](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-currency-currencyCode)

required, string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[accountType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditAccountDescriptor-accountType)

required, string

The account type. Plaid consumes basic balance account information from the `accounts/{accountId}` endpoint for a subset of the possible account types described in the FDX specification.  
  

Possible values: `LINEOFCREDIT`, `CHARGE`, `CREDITCARD`, `HOMELINEOFCREDIT`

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "accountId": "someLongTermUniqueIDString",
  "accountNumberDisplay": "4321",
  "productName": "Premier Account",
  "status": "OPEN",
  "currency": {
    "currencyCode": "CAD"
  },
  "accountType": "CREDITCARD"
}
```

\=\*=\*=\*=

#### Account statuses 

See the table below for help in selecting the appropriate account status.

| Status | Description |
| --- | --- |
| `CLOSED` | An account that is closed or no longer exists |
| `DELINQUENT` | An account with unpaid payments that are past due |
| `NEGATIVECURRENTBALANCE` | An account with a current negative balance |
| `PAID` | An account that is paid in full |
| `PENDINGCLOSE` | An account that is in the process of being closed |
| `PENDINGOPEN` | An account that is in the process of being opened |
| `RESTRICTED` | An account with restricted access |

\=\*=\*=\*=

#### Account types 

##### Annuity account types 

The `accountType` field for annuity accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `ANNUITY` | A form of insurance or investment entitling the investor to a series of annual sums |
| `FIXEDANNUITY` | A type of insurance contract that promises to pay the buyer a specific, guaranteed interest rate on their contributions to the account |
| `VARIABLEANNUITY` | A type of insurance contract that promises to pay back the buyer based on the performance of an underlying portfolio of mutual funds selected by the buyer |

##### Commercial account types 

The `accountType` field for accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `COMMERCIALDEPOSIT` | A deposit account for commercial customers, for example a business trust account |
| `COMMERCIALLOAN` | A preset borrowing limit that can be used at any time |
| `COMMERCIALLINEOFCREDIT` | An account with a preset borrowing limit that can be used at any time |
| `COMMERCIALINVESTMENT` | Investment Account for Commercial Customers. e.g. Commercial Brokerage Account |

##### Deposit account types 

The `accountType` field for deposit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `CHECKING` | An interest-bearing deposit account held at a bank or other financial institution |
| `SAVINGS` | An interest-bearing deposit account held at a bank or other financial institution |
| `CD` | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |
| `ESCROW` | A contractual arrangement in which a third party (the stakeholder or escrow agent) receives and disburses money or property for the primary transacting parties, with the disbursement dependent on conditions agreed to by the transacting parties |
| `MONEYMARKET` | A deposit account that pays interest based on current interest rates in the money markets |
| `OTHERDEPOSIT` | Use when none of the listed enums apply |

##### Insurance account types 

The `accountType` field for insurance accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LONGTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for an extended period of time, usually more than a year |
| `SHORTTERMDISABILITY` | Insurance that replaces a portion of the policyholder's income due to a disability for a short period of time, usually less than a year |
| `UNIVERSALLIFE` | A type of a cash value life insurance where the excess of premium payments above the current cost of insurance is credited to the cash value of the policy, which in turn is credited each month with interest |
| `WHOLELIFE` | Life insurance which is guaranteed to remain in force for the insured's entire lifetime, provided required premiums are paid, or to the maturity date |

##### Investment account types 

The `accountType` field for investment accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `401A` | An employer-sponsored money-purchase retirement plan that allows dollar or percentage-based contributions from the employer, the employee, or both |
| `401K` | An employer-sponsored defined-contribution pension account defined in subsection 401(k) of the Internal Revenue Code |
| `403B` | A U.S. tax-advantaged retirement savings plan available for public education organizations, some non-profit employers (only Internal Revenue Code 501(c)(3) organizations), cooperative hospital service organizations, and self-employed ministers in the United States |
| `529` | A tax-advantaged savings plan designed to help pay for education |
| `BROKERAGEPRODUCT` | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |
| `COVERDELL` | A trust or custodial account set up in the United States solely for paying qualified education expenses for the designated beneficiary of the account |
| `DIGITALASSET` | An account containing digital assets |
| `DEFINEDBENEFIT` | An employer-sponsored retirement plan where employee benefits are computed using a formula that considers several factors, such as length of employment and salary history |
| `ESOP` | An employee stock ownership plan (ESOP) is an employee benefit plan that gives workers ownership interest in the company |
| `GUARDIAN` | An account of a child in the parent's name, with legal title to the assets in the account, as well as all capital gains and tax liabilities produced from the account belonging to the parent |
| `INSTITUTIONALTRUST` | An institutional trust account |
| `IRA` | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |
| `KEOGH` | A tax-deferred pension plan available to self-employed individuals or unincorporated businesses for retirement purposes |
| `NONQUALIFIEDPLAN` | A type of tax-deferred employer-sponsored retirement plan that falls outside of ERISA guidelines |
| `OTHERINVESTMENT` | Use when none of the listed enums apply |
| `ROLLOVER` | An account containing investments rolled over from an employee-sponsored account |
| `ROTH` | An individual retirement account that offers tax-free growth and tax-free withdrawals in retirement |
| `SARSEP` | A simplified employee pension (SEP) plan set up before 1997 that includes a salary reduction arrangement |
| `TAXABLE` | A taxable investment account |
| `TDA` | TreasuryDirect Account |
| `TRUST` | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |
| `TERM` | Life insurance that provides coverage at a fixed rate of payments for a limited period of time |
| `UGMA` | Uniform Gifts to Minors Act account |
| `UTMA` | Uniform Transfers to Minors Act account |

##### Loan account types 

The `accountType` field for loan accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `AUTOLOAN` | A type of loan used to finance a car purchase |
| `HOMEEQUITYLOAN` | A type of loan in which the borrower uses the equity of his or her home as collateral |
| `INSTALLMENT` | A type of agreement or contract involving a loan that is repaid over time with a set number of scheduled payments |
| `LOAN` | The lending of money by one or more individuals, organizations, or other entities to other individuals, organizations etc. |
| `MILITARYLOAN` | A military loan |
| `MORTGAGE` | A type of loan you can use to buy or refinance a home |
| `PERSONALLOAN` | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |
| `SMBLOAN` | A small/medium business loan |
| `STUDENTLOAN` | A type of loan designed to help students pay for post-secondary education and the associated fees, such as tuition, books and supplies, and living expenses |

##### Line of credit account types 

The `accountType` field for line of credit accounts may be set to any of the following:

| Account type | Description |
| --- | --- |
| `LINEOFCREDIT` | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |
| `CHARGE` | An account to which goods and services may be charged on credit |
| `CREDITCARD` | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |
| `HOMELINEOFCREDIT` | A loan in which the lender agrees to lend a maximum amount within an agreed period, where the collateral is the borrower's equity in their house |

\=\*=\*=\*=

#### Transaction objects 

##### Deposit transaction 

A transaction on a deposit account type

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `DEPOSIT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[cardNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-cardNumberDisplay)

string

The payment card number (e.g. debit, credit or digital), suitably masked, used to originate the transaction. May differ from primary account number as a secondary or employee card or a one-time use number. This is an optional field and won't be returned for certain types of transactions such as cash or check deposits

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[payee](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-payee)

string

Payee name. This is deprecated and will be removed in a future major release in place of `transactionPayee` which provides detailed information of a payee's name and place of business on the `Transaction` entity  
  

Max length: `255`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#DepositTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "DEPOSIT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "ATM deposit",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 38.9
}
```

##### Investment transaction 

A transaction on an investment account. In addition to the required fields in the base `Transaction` model, Plaid requires the following fields for all transactions on an investment account:  

*   `fees`
*   `transactionType`

  
If the transaction involves a security, Plaid additionally requires the following fields:  

*   `unitPrice`
*   `units`
*   `symbol` OR both `securityId` and `securityIdType`

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `INVESTMENT_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[cardNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-cardNumberDisplay)

string

The payment card number (e.g. debit, credit or digital), suitably masked, used to originate the transaction. May differ from primary account number as a secondary or employee card or a one-time use number. This is an optional field and won't be returned for certain types of transactions such as cash or check deposits

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-transactionType)

required, string

The type of an investment transaction. Plaid maps these enums to Plaid [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Plaid doesn't map these enums to Plaid-specific transaction subtypes. Plaid maps these enums as follows:  

*   ADJUSTMENT - fee
*   ATM - cash
*   CASH - cash
*   CHECK - cash
*   CLOSURE - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CLOSUREOPT - Plaid suggests using SOLDTOCLOSE, PURCHASETOCLOSE, OPTIONEXERCISE or OPTIONEXPIRATION to indicate the specific type of closure, instead of using this enum.
*   CONTRIBUTION - buy (if transaction involves a security) or cash
*   DEP - cash
*   DEPOSIT - cash
*   DIRECTDEBIT - cash
*   DIRECTDEP - cash
*   DIV - cash
*   DIVIDEND - cash
*   DIVIDENDREINVEST - buy
*   EXPENSE - cash
*   FEE - fee
*   INCOME - cash
*   INTEREST - cash
*   INVEXPENSE - cash
*   JRNLFUND - transfer
*   JRNLSEC - transfer
*   MARGININTEREST - cash
*   OPTIONEXERCISE - transfer
*   OPTIONEXPIRATION - transfer
*   OTHER - cash - (unclassified)
*   PAYMENT - cash
*   POS - cash
*   PURCHASED - buy
*   PURCHASEDTOCOVER - buy
*   PURCHASETOCLOSE - buy
*   PURCHASETOOPEN - buy
*   REINVESTOFINCOME - buy
*   REPEATPMT - cash
*   RETURNOFCAPITAL - cash
*   SOLD - sell
*   SOLDTOCLOSE - sell
*   SOLDTOOPEN - sell
*   SPLIT - transfer
*   SRVCHG - fee
*   TRANSFER - transfer
*   XFER - transfer

  
  

Possible values: `ADJUSTMENT`, `ATM`, `CASH`, `CHECK`, `CLOSURE`, `CLOSUREOPT`, `CONTRIBUTION`, `DEP`, `DEPOSIT`, `DIRECTDEBIT`, `DIRECTDEP`, `DIV`, `DIVIDEND`, `DIVIDENDREINVEST`, `EXPENSE`, `FEE`, `INCOME`, `INTEREST`, `INVEXPENSE`, `JRNLFUND`, `JRNLSEC`, `MARGININTEREST`, `OPTIONEXERCISE`, `OPTIONEXPIRATION`, `OTHER`, `PAYMENT`, `POS`, `PURCHASED`, `PURCHASEDTOCOVER`, `PURCHASETOCLOSE`, `PURCHASETOOPEN`, `REINVESTOFINCOME`, `REPEATPMT`, `RETURNOFCAPITAL`, `SOLD`, `SOLDTOCLOSE`, `SOLDTOOPEN`, `SPLIT`, `SRVCHG`, `TRANSFER`, `XFER`

[securityId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-securityId)

string

If you return the `securityId` for a holding, Plaid uses it to look up the closing price from NYSE Group Security Master. If you don't return `securityId` for a holding that uses security IDs (not recommended), Plaid uses the `unitPrice` as the closing price.  
This field, along with `securityIdType` are **required** unless `symbol` is provided.  
**Note:** If `securityId` is provided, `securityIdType` is required.

[securityIdType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-securityIdType)

string

Plaid consumes solely CUSIP, ISIN, and SEDOL.  
This field, along with `securityId` are **required** unless `symbol` is provided.  
**Note:** If `securityIdType` is provided, `securityId` is required.  
  

Possible values: `CINS`, `CMC`, `CME`, `CUSIP`, `ISIN`, `ITSA`, `NASDAQ`, `SEDOL`, `SICC`, `VALOR`, `WKN`

[securityType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-securityType)

string

The type of a security  
  

Possible values: `BOND`, `DEBT`, `MUTUALFUND`, `DIGITALASSET`, `OPTION`, `OTHER`, `STOCK`, `SWEEP`

[symbol](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-symbol)

string

Ticker / Market symbol This field is **required** unless both `securityId` and `securityIdType` are provided

[commission](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-commission)

number

Plaid expects that your organization includes a value for commission if the commission isn't included in `fees`

[fees](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-fees)

required, number

Fees applied to the trade. Plaid expects that the `fees` include the commission, unless your organization separately provides a value for `commission`

[unitPrice](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-unitPrice)

number

Unit price. Plaid uses this as the [price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-investment-transactions-price) . Plaid falls back to using this as the [close price](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-close-price) if you don't return `securityId` for transactions involving securities. **Note:** This field is required if the transaction involves a security

[units](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-units)

number

Plaid requires this field for holdings and transactions involving securities. For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options.  
**Note:** This field is required if the transaction involves a security.

[unitType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-unitType)

string

The units of an investment transaction  
  

Possible values: `CURRENCY`, `SHARES`

[fiAttributes](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-fiAttributes)

\[object\]

Array of financial institution-specific attributes. Plaid recommends including a value for [is\_cash\_equivalent](https://plaid.com/docs/api/products/investments/index.html.md#investments-transactions-get-response-securities-is-cash-equivalent) property in this array. Plaid accepts `isCashEquivalent` as the attribute name and a string value of `true` or `false`.

[name](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-fiAttributes-name)

string

Name of the financial institution-specific attribute

[value](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#InvestmentTransaction-fiAttributes-value)

string

Value of the financial institution-specific attribute

```json
{
  "accountCategory": "INVESTMENT_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Share purchase",
  "debitCreditMemo": "DEBIT",
  "status": "PENDING",
  "amount": 428.08,
  "fees": 4.28,
  "transactionType": "PURCHASED"
}
```

##### Loan transaction 

A transaction on a loan account

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOAN_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[cardNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-cardNumberDisplay)

string

The payment card number (e.g. debit, credit or digital), suitably masked, used to originate the transaction. May differ from primary account number as a secondary or employee card or a one-time use number. This is an optional field and won't be returned for certain types of transactions such as cash or check deposits

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LoanTransaction-transactionType)

string

The type of a loan transaction. Plaid passes through all loan transaction types  

*   `ADJUSTMENT`: Adjustment or correction.
*   `FEE`: Fee charge. For example, a late payment fee.
*   `INTEREST`: Interest charge.
*   `PAYMENT`: Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages).
*   `LUMP_SUM_PAYMENT`: A single payment of money, as opposed to a series of payments made over time.
*   `SKIP_PAYMENT`: Payment that satisfies deferral of a required payment.
*   `DOUBLE_UP_PAYMENT`: Additional payment beyond the required payment to reduce the principal.
*   `PAYOFF`: Payment that satisfies the terms of the mortgage loan and completely pays off the debt.

  
  

Possible values: `ADJUSTMENT`, `FEE`, `INTEREST`, `PAYMENT`, `LUMP_SUM_PAYMENT`, `SKIP_PAYMENT`, `DOUBLE_UP_PAYMENT`, `PAYOFF`

```json
{
  "accountCategory": "LOAN_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Monthly loan payment-minimum due",
  "debitCreditMemo": "CREDIT",
  "status": "POSTED",
  "amount": 1638.83
}
```

##### Line of credit transaction 

A line-of-credit transaction

**Properties**

[accountCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-accountCategory)

required, string

The category of account. For example, annuity, commercial, deposit, digital wallet, insurance, investment, loan, or line of credit.  
  

Possible values: `LOC_ACCOUNT`

[transactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-transactionId)

required, string

Long term persistent identity of the transaction (unique to account). Plaid expects that `status: PENDING` and `status: POSTED` transactions have different IDs  
  

Max length: `256`

[referenceTransactionId](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-referenceTransactionId)

string

For reverse postings, the identity of the transaction being reversed. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction  
  

Max length: `256`

[postedTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-postedTimestamp)

string

The date and time that the transaction was posted to the account. This property is **required** by Plaid when `status=POSTED`. Plaid expects this property to be omitted when `status=PENDING` ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[transactionTimestamp](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-transactionTimestamp)

required, string

The date and time that the transaction was added to the server backend systems ISO 8601 date-time in format `YYYY-MM-DDThh:mm:ss.nnn[Z|[+|-]hh:mm]` according to [IETF RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)  
  

Format: `date-time`

[cardNumberDisplay](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-cardNumberDisplay)

string

The payment card number (e.g. debit, credit or digital), suitably masked, used to originate the transaction. May differ from primary account number as a secondary or employee card or a one-time use number. This is an optional field and won't be returned for certain types of transactions such as cash or check deposits

[description](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-description)

required, string

Description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer

[debitCreditMemo](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-debitCreditMemo)

required, string

The posting type of a transaction. Because the transaction `amount` is an absolute value, this parameter is required to indicate the transaction direction and sign (+/-):

*   `DEBIT`: Money is leaving the account. The transaction amount will be exposed with a **positive** sign (+)
*   `CREDIT`: Money is entering the account. The transaction amount will be exposed with a **negative** sign (-)
*   `MEMO`: The transaction is pending and will be completed at the end of the day. (Plaid handles `MEMO` transaction the same as `DEBIT` transactions.)

  
  

Possible values: `CREDIT`, `DEBIT`, `MEMO`

[category](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-category)

string

Transaction category, preferably MCC or SIC. Plaid expects your organization to provide MCC, if available and applicable

[subCategory](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-subCategory)

string

Transaction category detail specifying the standard of the transaction category. For example, "MCC"

[status](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-status)

required, string

The status of a transaction. Plaid consumes solely the `PENDING` and `POSTED` enums, and treats `MEMO` and `AUTHORIZATION` as if they were `PENDING`. Plaid expects that pending and posted transactions have different `transactionIds`.

*   `AUTHORIZATION`
*   `MEMO` - A pending transaction to be completed at the end of this day
*   `PENDING` - A pending transaction
*   `POSTED` - A posted transaction

  
  

Possible values: `AUTHORIZATION`, `MEMO`, `PENDING`, `POSTED`

[amount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-amount)

required, number

The amount of money in the account currency. The amount is an absolute value. Plaid relies on the `DebitCreditMemo` enum to determine the direction (and sign) of the transaction

[foreignAmount](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-foreignAmount)

number

The amount of money in the foreign currency. If this amount is specified, then Plaid expects that the `foreignCurrency` property is also set

[foreignCurrency](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-foreignCurrency)

string

Currency, fund and precious metal codes effective from June 25, 2024 per [ISO 4217 Currency Code Maintenance](https://www.six-group.com/en/products-services/financial-information/data-standards.html) . ZWL (the Zimbabwean dollar) expires August 31, 2024 and is deprecated and replaced with ZWG (Zimbabwe Gold), effective on June 25, 2024.  
  

Possible values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWG`, `ZWL`

[transactionType](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-transactionType)

string

The type of a line of credit (LOC) transaction. Plaid passes through all LOC transaction types  
  

Possible values: `ADJUSTMENT`, `CHECK`, `FEE`, `INTEREST`, `PAYMENT`, `WITHDRAWAL`, `PURCHASE`

[checkNumber](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md#LineOfCreditTransaction-checkNumber)

integer

Check number. Plaid expects this solely if the transaction involves a check

```json
{
  "accountCategory": "LOC_ACCOUNT",
  "transactionId": "78RJ3311PLU34300E",
  "transactionTimestamp": "2024-07-15T14:46:41.375+02:00",
  "description": "Recurring payment",
  "debitCreditMemo": "CREDIT",
  "status": "AUTHORIZATION",
  "amount": 38.9
}
```

\=\*=\*=\*=

#### Transaction types 

##### Investment transaction types 

Plaid maps these enums to Plaid investment transaction types [investment transaction types](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . but not to Plaid-specific transaction subtypes.

| Transaction type | [Investment transaction type](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) |
| --- | --- |
| `ADJUSTMENT` | `fee` |
| `ATM` | `cash` |
| `CASH` | `cash` |
| `CHECK` | `cash` |
| `CLOSURE` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CLOSUREOPT` | Plaid recommends against using this value, rather specifying the closure type with any of the following: `SOLDTOCLOSE`, `PURCHASETOCLOSE`, `OPTIONEXERCISE` or `OPTIONEXPIRATION` |
| `CONTRIBUTION` | `buy` (if transaction involves a security) or `cash` |
| `DEP` | `cash` |
| `DEPOSIT` | `cash` |
| `DIRECTDEBIT` | `cash` |
| `DIRECTDEP` | `cash` |
| `DIV` | `cash` |
| `DIVIDEND` | `cash` |
| `DIVIDENDREINVEST` | `buy` |
| `EXPENSE` | `cash` |
| `FEE` | `fee` |
| `INCOME` | `cash` |
| `INTEREST` | `cash` |
| `INVEXPENSE` | `cash` |
| `JRNLFUND` | `transfer` |
| `JRNLSEC` | `transfer` |
| `MARGININTEREST` | `cash` |
| `OPTIONEXERCISE` | `transfer` |
| `OPTIONEXPIRATION` | `transfer` |
| `OTHER` | `cash` (unclassified) |
| `PAYMENT` | `cash` |
| `POS` | `cash` |
| `PURCHASED` | `buy` |
| `PURCHASEDTOCOVER` | `buy` |
| `PURCHASETOCLOSE` | `buy` |
| `PURCHASETOOPEN` | `buy` |
| `REINVESTOFINCOME` | `buy` |
| `REPEATPMT` | `cash` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `RETURNOFCAPITAL` | `cash` |
| `SOLD` | `sell` |
| `SOLDTOCLOSE` | `sell` |
| `SOLDTOOPEN` | `sell` |
| `SPLIT` | `transfer` |
| `SRVCHG` | `fee` |
| `TRANSFER` | `transfer` |
| `XFER` | `transfer` |

##### Loan transaction types 

| Account type | Description |
| --- | --- |
| `ADJUSTMENT` | Adjustment or correction |
| `FEE` | Fee charge. For example, a late payment fee |
| `INTEREST` | Interest charge |
| `PAYMENT` | Required payment that satisfies the minimum payment (e.g. principal + interest for mortgages) |
| `LUMP_SUM_PAYMENT` | A single payment of money, as opposed to a series of payments made over time |
| `SKIP_PAYMENT` | Payment that satisfies deferral of a required payment |
| `DOUBLE_UP_PAYMENT` | Additional payment beyond the required payment to reduce the principal |
| `PAYOFF` | Payment that satisfies the terms of the mortgage loan and completely pays off the debt |

---


# Core Exchange - Authentication | Plaid Docs

Authentication 
===============

#### Authentication options for the Core Exchange API 

This API uses an [OpenID Connect (OIDC) authentication flow](https://plaid.com/core-exchange/authentication/) and accepts the resulting [access token](https://plaid.com/core-exchange/authentication/#response-parameters) as a bearer token. For example, `curl -H 'Authorization: Bearer <ACCESS_TOKEN>'`.

*   openIdConnectUrl: [https://www.your-organization.com/.well-known/openid-configuration](https://www.your-organization.com/.well-known/openid-configuration)

This API uses an [OAuth2.0 authorization code flow](https://plaid.comhttps://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/index.html.md) and accepts the resulting access token as a bearer token. For example, `curl -H 'Authorization: Bearer <ACCESS_TOKEN>'`.

Flows:

*   authorizationCode
    *   authorizationUrl: [https://www.your-organization.com/authorize](https://www.your-organization.com/authorize)
    *   tokenUrl: [https://www.your-organization.com/token](https://www.your-organization.com/token)
    *   scopes:
        *   Account: (optional) Read account data
        *   Customer: (optional) Read customer data
        *   Transactions: (optional) Read transaction data

---


# API Reference | Plaid Docs

API Reference 
==============

#### Endpoints and data definitions 

#### Core Exchange v6.3 

Reference for building the latest version of Plaid's FDX-aligned Core Exchange API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.3/index.html.md)

#### Core Exchange v6.2 

Reference for building Plaid's Core Exchange v6.2 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.2/index.html.md)

#### Core Exchange v6.1 

Reference for building Plaid's Core Exchange v6.1 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.1/index.html.md)

#### Core Exchange v6.0 

Reference for building Plaid's Core Exchange v6.0 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/6.0/index.html.md)

#### Core Exchange v5.3 

Reference for building Plaid's Core Exchange v5.3 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.3/index.html.md)

#### Core Exchange v5.2 

Reference for building Plaid's Core Exchange v5.2 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.2/index.html.md)

#### Core Exchange v5.1 

Reference for building Plaid's Core Exchange v5.1 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.1/index.html.md)

#### Core Exchange v5.0 

Reference for building Plaid's Core Exchange v5.0 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/5.0/index.html.md)

#### Core Exchange v4.6 

Reference for building Plaid's Core Exchange v4.6 API

[Endpoints & data dictionary](https://plaid.comhttps://plaid.com/core-exchange/docs/reference/4.6/index.html.md)

---


# User experience | Plaid Docs

User experience 
================

#### Plaid user experience guide 

[Plaid Link](https://plaid.com/docs/link/index.html.md) is the UI component users interact with to link their accounts to an app using Plaid. Your institution will show up in Plaid Link after you go live on Core Exchange.

#### Institution selection 

A user wants to connect their financial account to an app called WonderWallet. WonderWallet sends them to Plaid Link where they can select their financial institution. In this example, the financial institution is called First Platypus Bank.

(An image of "OAuth Example")

#### Data transparency messaging 

Data Transparency Messaging (DTM) gives consumers a way of understanding the data types needed to power an app or service that they want to use.

(An image of "Data transparency messaging example")

This enables Plaid and our customers to meet 1033 requirements: the 1033 rule requires that Plaid and our customers (third parties) disclose the data types they are requesting access to, and for which use cases. Additionally, Plaid customers need to ensure customer authorization is captured. With DTM, Plaid shows data types and use cases on behalf of the customer in Link, and then captures the authorization.

DTM will appear as a footer on the Pre-OAuth pane for all users that connect through OAuth.

Plaid and Plaid customers will only access the specific data the user has consented to via DTM. If additional data is required, the consumer will need to provide additional consent.

When an item has been created with DTM, Plaid will also expose the consent records including the use case, data types, and time stamp of consent via Permissions Manager—this ensures you have full visibility into the consumers’ consent, enabling you (as a Data Provider) to “confirm” authorization under the rule. If consent status or scope change on an item, such as if a user revokes access or grants additional access, these changes will also be reflected in the Permissions Manager records.

To ensure a consistent user experience and to avoid repetition, Plaid recommends that you do not include a description of the data scopes/fields shared in your OAuth flow.

#### Authentication Guidance 

##### OAuth 

The user is asked to authenticate with First Platypus. Plaid recommends you do this using the OAuth 2.0 protocol.

You own the OAuth user experience and host it on your domain. We encourage you have two screens with your logo prominently featured: a login screen and two-step verification screen.

Your OAuth flow must implement **strong authentication** and not solely rely on username/password, incorporating multi-factor authentication with one-time passcodes or stronger methods like push-based authentication or biometrics through [App2App or WebAuthn](https://plaid.comhttps://plaid.com/core-exchange/docs/user-experience/index.html.md#optional-components) .

(An image of "OAuth Authentication Example Login Page")

#### Account selection 

If the user has more than one financial account, the user returns to Plaid Link and is asked to select which accounts they’d like to link. The user then sees a success screen. Tapping the continue button will return them to WonderWallet.

(An image of "Account Selection Example")

#### Returning user experience 

Plaid’s returning user experience streamlines onboarding for users who have previously connected a financial account with Plaid via your institution’s OAuth and API integration.

In [Link](https://plaid.com/docs/link/index.html.md) , a user can choose to be remembered by Plaid by entering their phone number and then verifying it using a one-time password. Next, the user connects their account through your OAuth flow, which would be associated with their phone number. When the same user wants to connect their account to another app, Plaid enables the user to do so using their phone number and secure authentication methods like one-time passcodes and passkeys. This streamlined experience has built-in security controls and advanced monitoring that automatically detect suspicious activity and help prevent fraud.

As a data partner for Core Exchange, you’re automatically enabled for this streamlined experience with no integration work required. Your users can now opt-in and benefit from a faster way to securely connect their accounts to apps and services on the Plaid network.

#### Optional components 

##### App2app 

[App2app](https://openid.net/tag/app2app/) is a mechanism that allows mobile apps performing OAuth2 or OpenID Connect based authentication to offer a much simpler faster flow if the user already has an app provided by the authorization server owner installed on their mobile device. The example below uses App2app.

The user is brought to the First Platypus app to authenticate where they can use biometrics.

(An image of "App2app Example Login Page")

##### WebAuthn 

We also recommend using [WebAuthn](https://webauthn.guide/) for web-based authentication. Users can enroll and then easily use biometrics to authenticate on any web browser.

(An image of "WebAuthn Biometric Login Example")

---


# Account - Activity, logs, and status | Plaid Docs

Dashboard logs and troubleshooting 
===================================

#### Discover logging and troubleshooting information available in the Plaid Dashboard 

#### Logs for webhooks, Link, and API requests 

The Plaid Dashboard [Activity Log](https://dashboard.plaid.com/activity/usage) shows the past 14 days of API activity. Using the dashboard, you can see a record of all requests and responses, as well as all webhooks sent by the Plaid API, and all Link events.

(An image of "Plaid API logs showing request types, descriptions, institutions, environments, timestamps, and response codes in a dashboard.")

You can view the details of any request, response, webhook, or event, and view error information for any failed API request.

(An image of "Request and response details for failed API call: invalid public token expired. Error code 400, Halifax, Bank API, success rate 100%.")

##### Link analytics 

The [Link analytics](https://dashboard.plaid.com/link-analytics) page in the Dashboard shows a summary of Link conversion, along with top Link errors your users are experiencing and recommendations for increasing conversion. For more details, see [Link conversion](https://plaid.com/docs/link/best-practices/index.html.md) .

#### Logs for billable activity 

The Plaid Dashboard [Usage Page](https://dashboard.plaid.com/activity/usage) shows billable API usage for most Plaid products. Usage data is also available via the Plaid MCP server, allowing you to interact with this data via chat or an LLM agent. For more details, see the [blog post on the Plaid Dashboard MCP server](https://plaid.com/blog/plaid-mcp-ai-assistant-claude/) and the [Plaid Dashboard MCP server documentation](https://plaid.com/docs/resources/mcp/index.html.md) .

#### Logs for Payment Initiation, Transfer, and Signal 

The Payment Initiation (UK and Europe), Transfer, and Signal products also have their own logs in the Plaid Dashboard. If you are enabled for these products, links to view activity will appear in the Products menu within the dashboard. Using these logs, you can view the status and history of payment and transfer attempts, returns, and other product-specific information. For Payment Initiation and Transfer, this information is also available via the API; for more details, see the API documentation for [Payment Initiation](https://plaid.com/docs/api/products/payment-initiation/index.html.md) and [Transfer](https://plaid.com/docs/api/products/transfer/index.html.md) .

#### Audit logs 

Audit logs of activity occurring in the Dashboard is available to admins on teams with Premium Support Packages. To learn more about upgrading to a Premium Support Package, contact your Account Manager.

Dashboard audit logs include user identity, action type, IP address, and timestamps for core Dashboard actions. Audit log support for actions on product-specific Dashboard pages is not yet available.

#### Troubleshooting institution status 

The Plaid Dashboard contains an [Institution Status](https://dashboard.plaid.com/activity/status) pane, which allows you to view details and stats about institution connectivity over the past two weeks, as well as any recent downtime or special notes about the institution. You can also use this view to search institutions to see whether they are supported by Plaid and which Plaid products can be used with them. Most of this information is also available via the API; for more information on programmatically retrieving institution status, see [Institutions API endpoints](https://plaid.com/docs/api/institutions/index.html.md) .

##### Institution status details 

(An image of "Plaid status for a bank: Auth 100%, Identity 100%, Transactions 100%. Historical graph of item add success. All products 100% success rate.")

The graph at the top of the page shows institution status over the past two weeks, while the boxes below the graph show the current institution status. The time range used for calculating the current institution status may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more.

Plaid displays both Item add success rates (success adding new Items) and Item update success rates (success refreshing data for existing Items). The success rate as shown on the [main status page](https://dashboard.plaid.com/activity/status) is the Item add success rate.

All success rates reflect the percentage of successful attempts to retrieve data. Both Plaid errors and institution errors are combined when calculating the percentage of unsuccessful attempts. User errors, such as an Item add failing due to an incorrect password entered during Link, are not considered when calculating success rates.

All success rates are rounded down to the nearest percentage point. A success rate of 99% or higher indicates that the institution is considered healthy.

##### Institution migration status 

Within the Institutions Status page, you can use the [migration pane](https://dashboard.plaid.com/activity/status) to view the status of OAuth migrations. The migration pane shows all institutions with planned or current migrations and allows you to drill in to see the migration timeline and the impact on existing Items.

(An image of "Plaid migration status for a bank, in progress, type: Classic to API, timeline displayed.")

##### Insufficient data and delayed data 

If the institution has not had enough Plaid traffic during the window being evaluated to produce meaningful health data, the "Insufficient Data" message will be displayed. This is most likely to affect small institutions. If this occurs, try using the [Item Debugger](https://dashboard.plaid.com/activity/debugger) instead to diagnose the problem.

If Plaid has not been able to update data from the institution for over two days, the institution status may appear as "delayed". If it has been at least two weeks since the last successful institution update, or if Plaid is aware of a problem in updating data that is likely to take over two weeks to resolve, the institution status will appear as "stopped".

##### Alerting 

You can set up alerts to be notified of changes to the global Item add success rate of any institution. From [Settings > Team Settings > Communications](https://dashboard.plaid.com/settings/team/notification-preferences) , open the "Status alerts" tab to create an alert. You can also create an alert directly from the institution's status page. If you choose webhook-based alerting, the webhook that will be sent is the [INSTITUTION\_STATUS\_ALERT\_TRIGGERED](https://plaid.com/docs/api/institutions/index.html.md#institution_status_alert_triggered) webhook.

#### Troubleshooting with Item Debugger 

To view the status of a specific Item or Link session in the dashboard, you can use the [Item Debugger](https://dashboard.plaid.com/activity/debugger) . You can look up Items and Link sessions by `client_user_id`, `item_id`, `access_token`, `link_token`, or `link_session_id`. Troubleshooting information available includes error codes and suggested troubleshooting steps you can take to resolve any errors.

Access to the Item Debugger is also available via Plaid's Dashboard MCP server, allowing you to troubleshoot Item details via LLM chat or an agent. For more details, see the [blog post on the Plaid Dashboard MCP server](https://plaid.com/blog/plaid-mcp-ai-assistant-claude/) and the [Plaid Dashboard MCP server documentation](https://plaid.com/docs/resources/mcp/index.html.md) .

(An image of "Item debugger showing a healthy item for institution Juno with an ID, transactions updated 5 hours ago.")

---


# Account - Pricing and billing | Plaid Docs

Plaid pricing and billing 
==========================

#### Learn about pricing, what is considered a billable event, and how to monitor your bill 

#### Pricing information 

To view prices, [apply for Production access](https://dashboard.plaid.com/overview/request-products) . Pricing information for Pay as you go and Growth plans will be displayed on the last page before you submit your request. For Custom plans, select the Custom option and submit the form, and Sales will reach out to discuss pricing. Or, you can [contact Sales](https://plaid.com/contact/) to learn more about custom pricing.

#### Pricing plans 

Plaid offers three types of pricing plans:

*   **Pay as you go** – has no minimum spend or commitment.
*   **Growth** – Minimum spend, annual commitment. Lower per-use costs than Pay as you go plans.
*   **Custom (aka Scale)** – Higher minimum spend and annual commitment but provides access to the lowest per-use costs. Minimums can apply across the entire Plaid account or by product and can apply across both Plaid and Plaid Check. For a Custom plan, [contact Sales](https://plaid.com/contact/) .

To change your plan, see [Viewing or changing pricing plans](https://plaid.com/docs/account/billing/index.html.md#viewing-or-changing-pricing-plans) .

For customers based in the EU or UK, or who will be serving end users based in the EU or UK, only Custom plans are offered. In addition, Signal, Transfer, and Plaid Check products (e.g. Consumer Report) are currently offered only via Custom plans.

#### Pricing models 

Plaid has multiple different pricing models, depending on the product. These models only apply to Production traffic; usage of Sandbox is always free.

Note that the details outlined below are general information and guidance about typical pricing structures and policies for new customers. Your specific pricing and billing structure is governed by your agreement with Plaid. If you have questions about your bill, [contact Support](https://dashboard.plaid.com/support/new/admin/account-administration/pricing) .

Endpoints that are not associated with any particular product are typically available to Plaid customers free of charge. Examples of these free-to-use endpoints include [Institutions endpoints](https://plaid.com/docs/api/institutions/index.html.md) , [Item endpoints](https://plaid.com/docs/api/items/index.html.md) , [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) (not to be confused with [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) , which is associated with the Balance product), and [user management endpoints](https://plaid.com/docs/api/users/index.html.md) .

##### One-time fee 

You will incur charges for one-time fee products whenever the product is successfully added to an Item. This occurs when an Item has been successfully created by Link and this product was specified in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . An Item is typically considered to be successfully created if a `public_token` was exchanged, but sometimes (e.g. when using micro-deposit Auth flows, or the in-Link Identity Match flow) it may be considered created once the `public_token` was created. If the Item was not initialized with the product at the time of creation, the product can also be added to the Item later by calling a product endpoint belonging to that product on the Item.

For one-time fee products, it does not matter how many API calls are made for the Item (or user); the cost is the same regardless of whether the product's endpoints are called many times or zero times.

For the Auth and Identity products, if the product was added to the Item via the `optional_products` parameter in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, you will not incur charges for those products until their corresponding endpoint is called. For example, if you initialize an Item with `auth` in the `products` parameter and `identity` in the `optional_products` parameter, you will not be charged for Identity on that Item until you call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) for that access token. Note: Identity Match is a Per-request flat fee product, so calling [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) multiple times will result in repeated charges for Identity Match, but only one charge for Identity.

For Document Income and Payroll Income, charges will be incurred when data is available to be accessed. This will typically be indicated by the `INCOME_VERIFICATION` webhook firing with the status of `VERIFICATION_STATUS_PROCESSING_COMPLETE`. For Document Income, the fee depends on the documents processed and which processing options are enabled (i.e. fraud, document parsing, or both). For bank statements, the fee is based on the number of pages in the statement; for all other document types, there is a flat fee per document.

For Hosted Link, each session delivered via SMS or email will incur a one-time fee. There is no fee to use Hosted Link if you are not using Plaid to deliver sessions.

When using Transfer, each Item initialized with Transfer (unless created using the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint) will also incur the one-time Auth fee, and no additional fee will be incurred for using Auth endpoints with that Item.

Products that use one-time fee pricing are:

*   Auth
*   Identity
*   Income (except for [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) and [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) , which use per-request pricing)

##### Subscription fee 

Under the subscription fee model, an Item will incur a monthly subscription fee as long as a valid `access_token` exists for the Item. Removing the Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) will end the subscription. The subscription will also be ended if the end user depermissions their Item, such as via [my.plaid.com](https://my.plaid.com/) or by contacting Plaid support. If the end user depermissions the Item via their financial institution's portal, this may also end the subscription, although this is not guaranteed, as not all institutions notify Plaid about permissions revocations performed via their portals.

Once a subscription fee product has been added to an Item, it is not possible to end the subscription and leave the Item in place. The Item must be deleted, which can be done by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . If the Item's subscription is active, Plaid will charge for the subscription even if no API calls are made for the Item or API calls cannot be successfully made for the Item (e.g. because the Item is in an error state). Plaid's subscription cycle is based on calendar months in the UTC time zone; each month begins a new cycle. Fees for Items created or removed in the middle of the month are not pro-rated.

If you add a subscription-billed product to an Item using your free API request allocation (for example, by creating an Item initialized with Transactions, Investments, or Liabilities in Limited Production), you will be not be charged for that subscription unless you continue to use the Item after using up your free API requests and receiving full Production access.

When using subscription fee products in Production, it is important to persist the access token so that you can remove the Item when needed to avoid being billed indefinitely. If you have created access tokens for which you are being billed but did not store the tokens, [contact support](https://dashboard.plaid.com/support) for assistance.

Products that use subscription fee pricing are:

*   Transactions (except for the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint)
*   Recurring Transactions
*   Liabilities
*   Investments (except for the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint)

A single Item can have multiple different subscriptions on it (for example, Transactions and Liabilities), but the same subscription will not be added multiple times to the same Item.

Investments has two separate subscriptions that can be associated with an Item: Investments Holdings and Investments Transactions. Adding Investments to an Item via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or by calling [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) adds the Investments Holdings subscription. Calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) on an Item adds both the Investments Transactions and Investments Holdings subscriptions.

##### Per-request flat fee 

For per-request flat fee products, a flat fee is charged for each successful API call to that product endpoint.

Products and endpoints that use per-request flat fee pricing are:

*   Balance ([/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) )
*   Refresh endpoints, except for Statements Refresh ([/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) , [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) , [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) )
*   Asset report PDF and Audit Copy ([/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) , [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) )
*   Transfer Risk Engine ([/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) ), see [Transfer fee model](https://plaid.com/docs/account/billing/index.html.md#transfer-fee-model) for more details
*   Identity Match ([/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) ), see below for more details
*   Signal ([/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) )
*   Beacon Account Insights ([/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) )

There is also a flat fee for each link delivered through SMS or email via Link Delivery (beta), when using Hosted Link with the optional Link Delivery feature enabled.

Identity Match can optionally be enabled via the Dashboard. In this integration mode, the Identity Match check is automatically performed during Link and you never call the [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) endpoint directly. The billing trigger for Identity Match in this situation is when Plaid successfully obtains Identity data from the Item. If Plaid could not obtain any Identity data for the Item, you will not be billed.

##### Per-request flexible fee 

For per-request flexible fee products, a fee is charged for each successful API call to that product endpoint. The fee will vary depending on the amount of information requested in the API request.

For Assets, the fee is calculated based on the number of Items in the report as well as the number of days of history requested. An additional fee is charged for an Asset Report containing more than 5 Items; this fee will be charged twice if the Asset Report contains more than 10 Items, and so on. An "Additional History" fee is also charged for each Item for which more than 61 days of history is requested. The Additional History fee is a flat fee regardless of how many days of additional history are requested; it does not matter how many days beyond 61 are requested.

For Enrich, the flexible fee is based on the number of transactions sent to be enriched.

For [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) , the flexible fee is based on the number of statements available between the provided start and end dates found when calling [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) . Note that you will be charged for any statement extracted, even those that you previously requested at an earlier date.

Products that use per-request flexible fee pricing are:

*   Assets
*   Statements Refresh
*   Enrich

##### Per-Item flexible fee 

For per-Item flexible fee products, a fee is charged when the Item is created, which is deemed to occur when the `public_token` is created. The fee will vary depending on the amount of information requested when creating the Item.

For Statements, the flexible fee is calculated based on the number of statements available within the date range requested when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . The fee will be charged even if you do not call any Statements endpoints.

Products that use per-Item flexible fee pricing are:

*   Statements (excluding [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) , which is charged as a per-request flexible fee)

##### Payment Initiation fee model 

A fee is charged for each payment initiated. A payment is considered initiated if the end user reached the end of the payment flow and received a confirmation success screen. Standing orders (recurring payments) are considered a single payment but are billed on a separate pricing schedule from one-time payments. Fees will vary depending on the payment amount and the network used to transfer the payment.

##### Plaid Check fee model 

Most Plaid Check products are charged when the corresponding /get endpoint is called ([/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) , and [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) ). The exception is Partner Insights, which is charged when the associated report is first generated and `partner_insights` is specified in the product array, which can happen during [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , or [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) .

The Plaid Check fee model is similar to the one-time fee model. Like the one-time fee model, there is no additional charge to call an endpoint multiple times if the same Consumer Report is being retrieved each time. However, unlike the one-time fee model, if a new Consumer Report is generated for a given `user_token`, which can be done by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , a new set of fees will be incurred for calling a `/get/` endpoint on the new Consumer Report.

In addition to any product-specific charges, each Plaid Check Report incurs a Base Report charge. This fee is charged when the first `/get` endpoint is called for a given `user_token` and report.

For example, if you called [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) followed by [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , you would be charged the Base Report fee when [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) is called, but only charged the Income Insights fee when [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) is called. If you call the endpoints in the opposite order, calling [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) followed by [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , both the Base Report fee and Income Insights fee would be charged when [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) is called, and no fees would be charged when calling [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) .

For certain use cases, Plaid Check customers can select between different fee and billing models to accommodate different use cases and provide cost predictability. For details, [contact Sales](https://plaid.com/check/consumer-report/#contact-form) .

##### Transfer fee model 

When working with Transfer, there are three fees: The Auth fee, the Risk Engine Fee, and the per-transfer fee.

###### Auth fee 

When using Transfer, each Item with the Transfer product (unless created by the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint) will also have Auth added to the Item and will incur a one-time Auth fee in addition to the per-payment Transfer fee.

###### Risk Engine fee 

When using the Transfer Risk Engine, calls to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) will incur a per-request flat fee. If you have opted out of the Transfer Risk Engine and are instead checking for transfer risk in another way, such as via direct calls to Balance or Signal endpoints, you will not be charged for calls to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . If the Transfer Risk Engine is unable to assess the return risk of the transaction (i.e. it returns a value of `approved` with a non-`null` `rationale_code`), you will not be charged for the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call.

###### Per-transfer fee 

A fee is charged for each transfer made. A transfer is considered made if it was successfully created via [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . The per-transfer fee is charged even if the payment is later reversed or clawed back. In such cases, a reversed payment fee may be charged as well. Fees will vary depending on the payment amount and the network used to make the payment.

A per-transfer fee is also applied to funds transfers between your bank account and your balance held with Plaid, such as sweeps, or payments to and from the Plaid Ledger.

##### Monitor fee model 

Monitor uses a model with two fees:

*   A base fee, which is incurred the first time a new user is scanned
*   A rescanning fee, which is incurred based on the number of users rescanned each month

The rescanning fee is calculated based on the number of users on a rescanning program in a given month and works similarly to the subscription fee model. Plaid's subscription cycle is based on calendar months in the UTC time zone; each month begins a new cycle. Fees for users added to or removed from a rescanning program in the middle of the month are not pro-rated.

To avoid being rebilled for a user you no longer need recurring scans for (e.g., a user who has closed their account with you), create a program specifically for former users, make sure rescans are disabled, and move the user into that program when they are offboarded from your system.

##### Identity Verification fee model 

For Identity Verification, a fee is charged based on the end user performing certain activities during the Link flow. The following events are billed:

*   Anti-Fraud Engine (the first verification check run, typically when the end user enters their phone number to begin SMS verification. If this is skipped, the Anti-Fraud Engine fee will be incurred later on. For example, if the SMS check is skipped in favor of the document check, the document check will incur both the Anti-Fraud Engine fee and the document check fee.)
*   Data Source verification (cost varies based on the end user's country, see your pricing contract for details)
*   Document check
*   Selfie check

If a retry is issued for a session, the retry will be billed like a new session, including the Anti-Fraud Engine and any other verification checks included in the retried session.

#### Partnerships pricing 

If you are using a Plaid partner, you will be charged for Plaid API usage performed by the partner using your processor token in the same way as if the calls had been made by you. The partner's API usage will not be included in your Plaid Dashboard [usage report](https://dashboard.plaid.com/activity/usage) . If you have questions about the partner's API activity, contact the Plaid partner.

#### Viewing billable activity and invoices 

To view billable activity for your account, see the Production [Usage](https://dashboard.plaid.com/activity/usage) page on the Dashboard.

Invoices will be sent each month to the [billing contact](https://dashboard.plaid.com/settings/company/profile) configured for the team.

##### Setting cost centers 

For some products, you can set a cost center using the `PLAID-COST-CENTER-ID` header to set an arbitrary string of 3-30 printable ASCII characters as a cost center ID.

This header should be applied when calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . If the billable event occurs later (i.e. when using an endpoint billed on a per-request fee model, like [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) , or when using [post-Link initialization](https://plaid.com/docs/link/initializing-products/index.html.md#adding-products-post-link) it should be applied when calling the billable endpoint. For Identity Verification, the header should be added when calling [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) or [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) .

If a `PLAID-COST-CENTER-ID` is set, the cost center will be reported in billable activity reports and invoices.

Products that support setting cost centers are:

*   Auth
*   Identity
*   Identity Verification
*   Balance
*   Transactions

#### Updating payment information 

Pay as you go customers can update [payment method](https://dashboard.plaid.com/settings/team/billing) and [billing contact](https://dashboard.plaid.com/settings/company/profile) information on the Plaid Dashboard. Custom plan customers should contact their account manager to update this information.

#### Updating products 

To view your currently enabled products, see the [Products](https://dashboard.plaid.com/settings/team/products) page on the Dashboard under the Team Settings section. To add additional products to your Plaid account you can [submit the product request form](https://dashboard.plaid.com/overview/request-products) located on the Dashboard. This form is also accessible via the [Products](https://dashboard.plaid.com/settings/team/products) page.

#### Viewing or changing pricing plans 

To view current pricing or to switch between pricing plans, customers on Pay as you go or Growth plans can use the [Plans page](https://dashboard.plaid.com/settings/team/plans) within the Dashboard. Customers with Pay as you go plans can upgrade their plan at any time. Customers with Growth plans can submit a request to upgrade or downgrade their plan at any time; requests will take effect after the minimum commitment period on the existing Growth plan has been satisfied. Customers on Custom plans should [contact Support](https://dashboard.plaid.com/support/new/product-and-development) or their Plaid Account Manager.

---


# Account - Overview | Plaid Docs

Account Overview 
=================

#### Learn about your Plaid developer account 

#### Developer account overview 

Your Plaid developer account is managed through the [Plaid Dashboard](https://dashboard.plaid.com) .

(An image of "Plaid Dashboard with Institution Status, Usage, and Item Debugger options. Support shows recent case details and status.")

This section provides information on topics related to managing your Plaid developer account, such as [billing](https://plaid.com/docs/account/billing/index.html.md) , [account security](https://plaid.com/docs/account/security/index.html.md) , and [team membership](https://plaid.com/docs/account/teams/index.html.md) . You can also find information on [logging and troubleshooting](https://plaid.com/docs/account/activity/index.html.md) in the dashboard, including institution status details and logs of API activity on your account.

A Plaid developer account is different from a Plaid account at my.plaid.com. To manage the financial information you're sharing via Plaid, visit [my.plaid.com](https://my.plaid.com/) .

---


# Account - For resellers | Plaid Docs

Resellers 
==========

#### Create and manage your customers 

The Reseller Dashboard and API are functionality that Plaid has developed to support our authorized Reseller Partners. If you don't have a formal partnership established with Plaid, [contact us](https://plaid.com/contact/) to learn about signing up or to receive the appropriate contractual agreements to unlock this functionality.

#### Overview 

This guide explains how an authorized Plaid Reseller Partner can create and manage their End Customer teams. Each one of your End Customers is required to have a unique set of Plaid API keys, which enables reporting their billable usage, filing and managing support issues, customizing their Plaid Link experience, and registering their applications with our financial institution partners.

#### Configuring your Reseller Partner team 

When you join the Plaid Reseller Partner program, you will work with your Partner Account Manager to set up a Reseller Partner team for your company.

Get started by [signing up](https://dashboard.plaid.com/signup) for a Dashboard account, which will automatically create a team for you. Next, talk to your Partner Account Manager to configure your team as a Reseller Partner team.

If you already have a Plaid Dashboard account, or are using Plaid for a separate use case or business line, we require that you create a separate Reseller Partner team. You can use the same Dashboard user account (email address) to access both teams.

#### Methods for creating and managing End Customers 

Plaid offers two ways to create and manage End Customers:

1.  The Dashboard (described in this guide)
2.  The reseller API (documented in the [reseller API reference docs](https://plaid.com/docs/api/partner/index.html.md) )

The steps described in [Configuring your Reseller Partner team](https://plaid.com/docs/account/resellers/index.html.md#configuring-your-reseller-partner-team) are required regardless of whether you use the Dashboard or the reseller API.

If you expect to onboard a large number of End Customers, or if you'd like to minimize the amount of manual work required by your operations staff, we strongly recommend that you integrate with our [reseller API](https://plaid.com/docs/api/partner/index.html.md) , which allows you to programmatically incorporate End Customer creation and management into your onboarding flows.

Whether you create End Customers programmatically via the reseller API or manually in the Dashboard, they will be visible and active in both places. For example, if you create an End Customer via the API, you will be able to view it in the Dashboard, and vice versa.

Under the hood, the reseller API and the Dashboard behave identically and follow the same onboarding process, which is described in [Creating End Customers](https://plaid.com/docs/account/resellers/index.html.md#creating-end-customers) .

#### Viewing the Dashboard as a Reseller Partner 

Being a member of a Reseller Partner team automatically grants you permission to create and manage End Customers. However, you must first switch to your Reseller Partner team in the Dashboard to exercise these permissions.

Ensure that your Reseller Partner team's name appears in the top left-hand corner of the Dashboard. If a different team's name is displayed, click the team's name to open the team switcher and then select your Reseller Partner team's name:

(An image of "Dropdown menu showing selected team 'My reseller team' and option to 'Create new team.'")

If your Reseller Partner team does not appear in the list (which can happen if you have a lot of End Customers), you will first need to go to the Teams page. Click on your name in the bottom-left corner of any page and select [Teams](https://dashboard.plaid.com/personal/teams) .

(An image of "Dropdown menu with options: Profile, Security, Teams, Logout; associated with user section labeled 'My Name'.")

You can then access reseller partner features in the navigation bar on the left side of the dashboard

(An image of "Manage End Customers: Options for Summary, Support, and Usage with icons for each.")

#### Creating End Customers 

First, follow the instructions in [Viewing the Dashboard as a Reseller Partner](https://plaid.com/docs/account/resellers/index.html.md#viewing-the-dashboard-as-a-reseller-partner) .

Next, select the team switcher in top left-hand corner and then click **Create new team**. Fill out and submit the form.

Once you have created the End Customer, it will appear in the [Partner End Customer Summary](https://dashboard.plaid.com/partner/customers-summary) page:

(An image of "Partner End Customer Summary page with search, filter by Production and OAuth Status, create button, list of end customers.")

You can view the newly created End Customer's API keys by clicking on the End Customer and navigating to the Developers > [Keys](https://dashboard.plaid.com/developers/keys) tab. The customer will automatically be enabled Sandbox and Limited Production to facilitate testing.

The newly created End Customer will be assigned a _status_, which will change as they move through the onboarding process. The possible statuses are described below:

*   `UNDER REVIEW`: You successfully created the End Customer, but more information is needed before Plaid can approve or deny them. This status is most commonly seen when the newly created End Customer is already a Plaid customer, in which case you will need to talk with your Partner Account Manager to resolve the channel conflict.
*   `DENIED`: You successfully created the End Customer, but Plaid has determined that we cannot service them through your reseller contract. This status is most commonly seen in the case of channel conflicts (i.e., Plaid already has a contract with this End Customer).
*   `PENDING ENABLEMENT`: You successfully created the End Customer and Plaid has approved them. You may now enable the End Customer (see the next section, [Enabling End Customers](https://plaid.com/docs/account/resellers/index.html.md#enabling-end-customers) , for details on the enablement process).
*   `ACTIVE`: You successfully created and enabled the End Customer. The End Customer's API keys can now be used in the Production environment.

#### Enabling End Customers 

When you create an End Customer, they will be enabled in Sandbox and Limited Production. This allows you to test your End Customers prior to enabling them for full Production access. It also prevents you from accidentally incurring billable activity prior to launching with your End Customers.

To enable an End Customer, find the end customer you wish to enable in the [Partner End Customer Summary](https://dashboard.plaid.com/partner/customers-summary) page, and then click the **Enable** button. Alternatively, you can select their team to navigate to the [Overview](https://dashboard.plaid.com/overview) page and then click **Get production access**.

Enablement happens instantly. Once the End Customer has been enabled for full Production, you will be able to make API calls to Plaid in the full Production environment. Any remaining unused credits for free API calls will _not_ carry over into full Production.

When you enable an End Customer, Plaid will automatically begin registering them with financial institutions that require OAuth access for connectivity, such as Chase and Capital One. Registration at most institutions happens within 24 hours, but for some institutions it may take several weeks. You can check the registration status for all OAuth institutions via the [OAuth institutions](https://dashboard.plaid.com/settings/compliance/us-oauth-institutions) page for a given End Customer.

Alternatively, you can set up a webhook in the dashboard to get automatically notified when an End Customer has their OAuth status updated. To configure the webhook, go to the [webhooks page](https://dashboard.plaid.com/developers/webhooks) and create a new webhook listening to the **End Customer OAuth status updated** event type. For details on the webhook, see the [partner API documentation](https://plaid.com/docs/api/partner/index.html.md#partner_end_customer_oauth_status_updated) .

If you encounter errors during OAuth registration, or if after 3 business days your end customer has not been registered at _any_ OAuth institutions, contact your Partner Account Manager for help.

#### Managing End Customers 

All of your end customers' support tickets are searchable in the [Partner End Customer Support](https://dashboard.plaid.com/partner/customers-support) page, and their API usage data can be found in the [Partner End Customer Usage](https://dashboard.plaid.com/partner/customers-usage) page.

#### Deleting End Customers 

In some cases you may wish to delete an End Customer prior to enabling them for Production, possibly because they were created in error or because they are no longer working with you.

To delete an End Customer, go to the [Partner End Customer Summary](https://dashboard.plaid.com/partner/customers-summary) page, and then click **Delete**:

(An image of "Deleting an End Customer confirmation with Yes and No options. Lists End Customer 0-2, dates, status, and actions.")

Deleting the End Customer will immediately deactivate their API keys and remove them from view in the Dashboard. This feature does not work for Production-enabled End Customers (those with a status of `ACTIVE`). To delete a Production-enabled customer, contact your Partner Account Manager.

---


# Account - Security | Plaid Docs

Plaid Dashboard account security and account management 
========================================================

#### Learn how to protect and manage your Plaid Dashboard account 

#### Password resets 

To reset your password, log in to the Plaid Dashboard, then access the [Personal Security page](https://dashboard.plaid.com/personal/security) , which contains a password reset screen.

If you ever forget your password to your Plaid Dashboard account, use the **Password reset** button on the login page to reset your password. You will only be able to receive your password reset email if you have verified your Plaid email address. If your email address is unverified, search your email for a message from [no-reply@plaid.com](https://plaid.commailto:no-reply@plaid.com) with the subject line "Confirm your email" and click on the link in that email to verify your address. You should then be able to reset your password.

#### Two-factor authentication 

Plaid allows you to enable two-factor authentication for your dashboard account via either text message or app-based authentication. After you enable two-factor authentication, you’ll be prompted to enter an authentication code each time you sign in. When you enable two-factor authentication, Plaid will show you a backup recovery code. Be sure to write down the recovery code and store it in a safe place, since it will only be displayed once.

To check whether your team members have enabled two-factor authentication, you can visit the [Team Members page](https://dashboard.plaid.com/settings/team/members) , where your team members' status will be displayed as "2FA ON", "2FA OFF", or "PENDING".

#### SSO login 

Plaid offers SSO (single sign-on) login to the Plaid Dashboard for all customers, except those on Pay-as-you-go-plans. We support all major identity providers, including Okta, Google Workspaces, OneLogin, and over 30 others. You can enable your account for SSO via the Dashboard, under [Settings > Team Settings > SSO](https://dashboard.plaid.com/settings/team/sso) . There is no additional charge for SSO enablement.

SAML support is available to customers on Plus or Premium Support packages, and SCIM support is available to customers on Premium Support packages only. To learn more, contact your Account Manager.

#### Rotating keys 

If your `secret` is ever compromised, you should rotate it from the [Keys](https://dashboard.plaid.com/developers/keys) section of the Dashboard. Clicking the **Rotate secret** button will generate a new secret, which you can then copy and test. The old secret will still remain active until you delete it by clicking the **Delete** button.

#### Managing notification settings 

To control which emails you receive from Plaid, you can update your [notification settings](https://dashboard.plaid.com/settings/team/notification-preferences) in the Dashboard.

#### Deleting accounts 

To leave or delete a team, see [Leaving or deleting a team](https://plaid.com/docs/account/teams/index.html.md#leaving-or-deleting-a-team) .

To delete your Plaid Dashboard login itself, [contact Support](https://dashboard.plaid.com/support/new/product-and-development/account-administration/delete-account) . Note that deleting your login is irreversible.

A Plaid Dashboard account is different from a Plaid account at my.plaid.com. To manage the financial information you're sharing via Plaid, visit [my.plaid.com](https://my.plaid.com/) .

---


# Account - Teams | Plaid Docs

Plaid teams 
============

#### Learn about Plaid teams 

Your Plaid Dashboard account can create or join multiple teams to enable collaboration across different teams or companies.

You can be a member of multiple Plaid teams, each with their own API keys and billing information.

#### Creating a team 

At the top-left of your Plaid Dashboard, click the team name drop-down and select **Create new team**.

(An image of "Dropdown displaying team options: WonderWallet, WonderWallet Team 2, WizardCash, and option to create a new team.")

Once you have submitted your team name and purpose into the form, click **Create team**. Your new team will come with a fresh set of API keys which can be used to build a new Plaid integration.

#### Managing your team membership 

You can create a new team, view your existing teams, and leave a team from the [Personal menu](https://dashboard.plaid.com/personal/teams) , found at the bottom-left of your Plaid Dashboard:

(An image of "Personal menu with options: Profile, Security, Teams, Logout for Plaid User; dropdown indicator present.")

#### Team-specific settings 

Visit [Settings > Team Settings](https://dashboard.plaid.com/settings/company/profile) in your Plaid Dashboard to view your company information, team members, billing settings, and invoices:

(An image of "Company and team settings menu with options for profile, branding, members, products, communication, link migrations, and compliance.")

#### Managing team member permissions 

From the Team Settings menu, you can also add and remove team members, as long as you have the Team management permission. You can assign specific permissions to each team member that you add to your Plaid team.

Members with the **Admin** permission are automatically granted all permissions to the entire Plaid Dashboard.

Members with the **Team Management** permission have similar access to the Admin permission – they can see and manage almost everything. However, they can't view or change API keys or view and file Support tickets. Some of what this role can do:

*   Make production / product requests
*   Change API configurations (OAuth redirect URIs, change pinned API version)
*   Configure webhooks
*   Configure team’s display settings and name
*   Manage billing / invoices
*   Manage team membership
*   Manage OAuth migrations
*   Delete the team

Members with the **Support** permission have access to the Support pages for viewing and filing support tickets.

Members with the **Link Customization Write Access** permission can create or edit Link customizations.

Certain pages are accessible to all Dashboard team members, regardless of their permissions. These pages include:

*   Overview
*   Status
*   Logs
*   Usage
*   Analytics

You can also use the Team Settings page to control which environments team members have access to. In order to view the team's `client_id`, team members must have access to at least one environment.

##### Identity Verification, Monitor, and Beacon permissions 

Members with Admin or Team Management permissions are able to assign granular permissions for Plaid Identity Verification, Monitor, and Beacon. There are numerous permission settings, which allow you to define who should be able to view certain information (e.g. end user PII) and take various actions. These permissions can be assigned while adding a team member or editing permissions for existing team members in the [Team Settings](https://dashboard.plaid.com/settings/team/members) page. Note that 2FA will need to be enabled for a user to be able to access this data.

##### Transfer Dashboard permissions 

See the [Transfer Dashboard documentation](https://plaid.com/docs/transfer/dashboard/index.html.md#dashboard-permissions) for details on Transfer-specific Dashboard permissions.

##### Credit Dashboard permissions 

*   **Credit Dashboard All Permissions** - Grants access to all Credit Dashboard features.
    *   **Credit Dashboard Access** - Grants access to view Credit Dashboard
    *   **Credit Dashboard Application Creation** - Grants ability to create hosted link URLs
    *   **Credit Dashboard User Profile Access** - Grants access to view Credit Dashboard user profiles
    *   **Credit Dashboard View PII** - Allows viewing of PII on Credit Dashboard

#### Consolidating multiple accounts using teams 

Teams prevent you from having to maintain multiple developer accounts. However, if you have already created multiple accounts, you can still consolidate them into a single account without having to create new keys or re-apply for access. To do so, follow these steps:

1.  Select an account to be the new primary account that will contain all the teams.
    
2.  From each account that you will be consolidating into the new primary account, invite the new primary account to the team.
    
3.  From each account that you will be consolidating into the new primary account, create a new empty team.
    
4.  From the new primary account, accept the invitations.
    
5.  From each account that you will be consolidating into the new primary account, leave the old team.
    

Your teams will now be consolidated under the new account.

#### Leaving or deleting a team 

To leave or delete a team, click on your name in the lower-left corner of the Dashboard and select **Teams** to access the [Teams page](https://dashboard.plaid.com/personal/teams) . Click on the **...** button on the right side of the team's listing. Select **Leave Team** or **Delete Team**. Deleting the team will remove access to the team for all users, and the API keys for team will be deactivated. You must have the Team Management permission to delete a team.

---


# API - Accounts | Plaid Docs

Accounts 
=========

#### API reference for retrieving account information and seeing all possible account types and subtypes 

\=\*=\*=\*=

#### /accounts/get 

#### Retrieve accounts 

The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint can be used to retrieve a list of accounts associated with any linked Item. Plaid will only return active bank accounts — that is, accounts that are not closed and are capable of carrying a balance. To return new accounts that were created after the user linked their Item, you can listen for the [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhook and then use Link's [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to request that the user share this new account with you.  
[/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) is free to use and retrieves cached information, rather than extracting fresh information from the institution. The balance returned will reflect the balance at the time of the last successful Item update. If the Item is enabled for a regularly updating product, such as Transactions, Investments, or Liabilities, the balance will typically update about once a day, as long as the Item is healthy. If the Item is enabled only for products that do not frequently update, such as Auth or Identity, balance data may be much older.  
For realtime balance information, use the paid endpoint [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) instead.

#### Request fields and example 

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /accounts/get results.

**options->account\_ids** (\[string\])  
An array of account\_ids to retrieve for the Account.

```javascript
const request: AccountsGetRequest = {
  access_token: ACCESS_TOKEN,
};
try {
  const response = await plaidClient.accountsGet(request);
  const accounts = response.data.accounts;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
An array of financial institution accounts associated with the Item. If /accounts/balance/get was called, each account will include real-time balance information.

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "holder_category": "personal",
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "6PdjjRP6LmugpBy5NgQvUqpRXMWxzktg3rwrk",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    },
    {
      "account_id": "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": [
      "assets",
      "auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "institution_name": "Royal Bank of Plaid",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "bkVE1BHWMAZ9Rnr"
}
```

\=\*=\*=\*=

#### Account type schema 

The schema below describes the various `types` and corresponding `subtypes` that Plaid recognizes and reports for financial institution accounts. For a mapping of supported types and subtypes to Plaid products, see the [Account type / product support matrix](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) .

#### Properties 

**depository** (string)  
An account type holding cash, in which funds are deposited.

**depository->cash management** (string)  
A cash management account, typically a cash account at a brokerage

**depository->cd** (string)  
Certificate of deposit account

**depository->checking** (string)  
Checking account

**depository->ebt** (string)  
An Electronic Benefit Transfer (EBT) account, used by certain public assistance programs to distribute funds (US only)

**depository->hsa** (string)  
Health Savings Account (US only) that can only hold cash

**depository->money market** (string)  
Money market account

**depository->paypal** (string)  
PayPal depository account

**depository->prepaid** (string)  
Prepaid debit card

**depository->savings** (string)  
Savings account

**credit** (string)  
A credit card type account.

**credit->credit card** (string)  
Bank-issued credit card

**credit->paypal** (string)  
PayPal-issued credit card

**loan** (string)  
A loan type account.

**loan->auto** (string)  
Auto loan

**loan->business** (string)  
Business loan

**loan->commercial** (string)  
Commercial loan

**loan->construction** (string)  
Construction loan

**loan->consumer** (string)  
Consumer loan

**loan->home equity** (string)  
Home Equity Line of Credit (HELOC)

**loan->line of credit** (string)  
Pre-approved line of credit

**loan->loan** (string)  
General loan

**loan->mortgage** (string)  
Mortgage loan

**loan->other** (string)  
Other loan type or unknown loan type

**loan->overdraft** (string)  
Pre-approved overdraft account, usually tied to a checking account

**loan->student** (string)  
Student loan

**investment** (string)  
An investment account. In API versions 2018-05-22 and earlier, this type is called brokerage.

**investment->529** (string)  
Tax-advantaged college savings and prepaid tuition 529 plans (US)

**investment->401a** (string)  
Employer-sponsored money-purchase 401(a) retirement plan (US)

**investment->401k** (string)  
Standard 401(k) retirement account (US)

**investment->403B** (string)  
403(b) retirement savings account for non-profits and schools (US)

**investment->457b** (string)  
Tax-advantaged deferred-compensation 457(b) retirement plan for governments and non-profits (US)

**investment->brokerage** (string)  
Standard brokerage account

**investment->cash isa** (string)  
Individual Savings Account (ISA) that pays interest tax-free (UK)

**investment->crypto exchange** (string)  
Standard cryptocurrency exchange account

**investment->education savings account** (string)  
Tax-advantaged Coverdell Education Savings Account (ESA) (US)

**investment->fixed annuity** (string)  
Fixed annuity

**investment->gic** (string)  
Guaranteed Investment Certificate (Canada)

**investment->health reimbursement arrangement** (string)  
Tax-advantaged Health Reimbursement Arrangement (HRA) benefit plan (US)

**investment->hsa** (string)  
Non-cash tax-advantaged medical Health Savings Account (HSA) (US)

**investment->ira** (string)  
Traditional Individual Retirement Account (IRA) (US)

**investment->isa** (string)  
Non-cash Individual Savings Account (ISA) (UK)

**investment->keogh** (string)  
Keogh self-employed retirement plan (US)

**investment->lif** (string)  
Life Income Fund (LIF) retirement account (Canada)

**investment->life insurance** (string)  
Life insurance account

**investment->lira** (string)  
Locked-in Retirement Account (LIRA) (Canada)

**investment->lrif** (string)  
Locked-in Retirement Income Fund (LRIF) (Canada)

**investment->lrsp** (string)  
Locked-in Retirement Savings Plan (Canada)

**investment->mutual fund** (string)  
Mutual fund account

**investment->non-custodial wallet** (string)  
A cryptocurrency wallet where the user controls the private key

**investment->non-taxable brokerage account** (string)  
A non-taxable brokerage account that is not covered by a more specific subtype

**investment->other** (string)  
An account whose type could not be determined

**investment->other annuity** (string)  
An annuity account not covered by other subtypes

**investment->other insurance** (string)  
An insurance account not covered by other subtypes

**investment->pension** (string)  
Standard pension account

**investment->prif** (string)  
Prescribed Registered Retirement Income Fund (Canada)

**investment->profit sharing plan** (string)  
Plan that gives employees share of company profits

**investment->qshr** (string)  
Qualifying share account

**investment->rdsp** (string)  
Registered Disability Savings Plan (RSDP) (Canada)

**investment->resp** (string)  
Registered Education Savings Plan (Canada)

**investment->retirement** (string)  
Retirement account not covered by other subtypes

**investment->rlif** (string)  
Restricted Life Income Fund (RLIF) (Canada)

**investment->roth** (string)  
Roth IRA (US)

**investment->roth 401k** (string)  
Employer-sponsored Roth 401(k) plan (US)

**investment->rrif** (string)  
Registered Retirement Income Fund (RRIF) (Canada)

**investment->rrsp** (string)  
Registered Retirement Savings Plan (Canadian, similar to US 401(k))

**investment->sarsep** (string)  
Salary Reduction Simplified Employee Pension Plan (SARSEP), discontinued retirement plan (US)

**investment->sep ira** (string)  
Simplified Employee Pension IRA (SEP IRA), retirement plan for small businesses and self-employed (US)

**investment->simple ira** (string)  
Savings Incentive Match Plan for Employees IRA, retirement plan for small businesses (US)

**investment->sipp** (string)  
Self-Invested Personal Pension (SIPP) (UK)

**investment->stock plan** (string)  
Standard stock plan account

**investment->tfsa** (string)  
Tax-Free Savings Account (TFSA), a retirement plan similar to a Roth IRA (Canada)

**investment->thrift savings plan** (string)  
Thrift Savings Plan, a retirement savings and investment plan for Federal employees and members of the uniformed services.

**investment->trust** (string)  
Account representing funds or assets held by a trustee for the benefit of a beneficiary. Includes both revocable and irrevocable trusts.

**investment->ugma** (string)  
'Uniform Gift to Minors Act' (brokerage account for minors, US)

**investment->utma** (string)  
'Uniform Transfers to Minors Act' (brokerage account for minors, US)

**investment->variable annuity** (string)  
Tax-deferred capital accumulation annuity contract

**payroll** (string)  
A payroll account.

**payroll->payroll** (string)  
Standard payroll account

**other** (string)  
Other or unknown account type.

\=\*=\*=\*=

#### Account type / product support matrix 

The chart below indicates which products can be used with which account types. Note that some products can only be used with certain subtypes:

*   Auth and Signal require a debitable `checking`, `savings`, or `cash management` account.
*   Liabilities does not support `loan` types other than `student` or `mortgage`.
*   Transactions does not support `loan` types other than `student`. (For Canadian institutions, Transactions also supports the `mortgage` loan type.)
*   Investments does not support `depository` types other than `cash management`.

Also note that not all institutions support all products; for details on which products a given institution supports, use [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) or look up the institution on the [Plaid Dashboard status page](https://dashboard.plaid.com/activity/status) .

| Product | Depository | Credit | Investments | Loan | Other |
| --- | --- | --- | --- | --- | --- |
| [Balance](https://plaid.com/docs/balance/index.html.md) |  |  | \* |  |  |
| [Transactions](https://plaid.com/docs/transactions/index.html.md) |  |  |  |  |  |
| [Identity](https://plaid.com/docs/identity/index.html.md) |  |  |  |  |  |
| [Assets](https://plaid.com/docs/assets/index.html.md) |  |  |  |  |  |
| [Consumer Reports by Plaid Check](https://plaid.com/docs/check/index.html.md) |  |  |  |  |  |
| [Investments](https://plaid.com/docs/investments/index.html.md) |  |  |  |  |  |
| [Investments Move](https://plaid.com/docs/investments/index.html.md) |  |  |  |  |  |
| [Liabilities](https://plaid.com/docs/liabilities/index.html.md) |  |  |  |  |  |
| [Auth](https://plaid.com/docs/auth/index.html.md) |  |  |  |  |  |
| [Transfer](https://plaid.com/docs/transfer/index.html.md) |  |  |  |  |  |
| [Income (Bank Income flow)](https://plaid.com/docs/income/index.html.md) |  |  |  |  |  |
| [Statements](https://plaid.com/docs/statements/index.html.md) |  |  |  |  |  |
| [Signal](https://plaid.com/docs/signal/index.html.md) |  |  |  |  |  |
| [Payment Initiation (UK and Europe)](https://plaid.com/docs/payment-initiation/index.html.md) |  |  |  |  |  |
| [Virtual Accounts (UK and Europe)](https://plaid.com/docs/payment-initiation/index.html.md) |  |  |  |  |  |

\* Investments holdings data is not priced intra-day.

\=\*=\*=\*=

#### Currency code schema 

The following currency codes are supported by Plaid.

#### Properties 

**iso\_currency\_code** (string)  
Plaid supports all ISO 4217 currency codes.

**unofficial\_currency\_code** (string)  
List of unofficial currency codes

**unofficial\_currency\_code->ADA** (string)  
Cardano

**unofficial\_currency\_code->BAT** (string)  
Basic Attention Token

**unofficial\_currency\_code->BCH** (string)  
Bitcoin Cash

**unofficial\_currency\_code->BNB** (string)  
Binance Coin

**unofficial\_currency\_code->BTC** (string)  
Bitcoin

**unofficial\_currency\_code->BTG** (string)  
Bitcoin Gold

**unofficial\_currency\_code->BSV** (string)  
Bitcoin Satoshi Vision

**unofficial\_currency\_code->CNH** (string)  
Chinese Yuan (offshore)

**unofficial\_currency\_code->DASH** (string)  
Dash

**unofficial\_currency\_code->DOGE** (string)  
Dogecoin

**unofficial\_currency\_code->ETC** (string)  
Ethereum Classic

**unofficial\_currency\_code->ETH** (string)  
Ethereum

**unofficial\_currency\_code->GBX** (string)  
Pence sterling, i.e. British penny

**unofficial\_currency\_code->LSK** (string)  
Lisk

**unofficial\_currency\_code->NEO** (string)  
Neo

**unofficial\_currency\_code->OMG** (string)  
OmiseGO

**unofficial\_currency\_code->QTUM** (string)  
Qtum

**unofficial\_currency\_code->USDT** (string)  
Tether

**unofficial\_currency\_code->XLM** (string)  
Stellar Lumen

**unofficial\_currency\_code->XMR** (string)  
Monero

**unofficial\_currency\_code->XRP** (string)  
Ripple

**unofficial\_currency\_code->ZEC** (string)  
Zcash

**unofficial\_currency\_code->ZRX** (string)  
0x

\=\*=\*=\*=

#### Investment transaction types schema 

Valid values for investment transaction types and subtypes. Note that transactions representing inflow of cash will appear as negative amounts, outflow of cash will appear as positive amounts.

#### Properties 

**buy** (string)  
Buying an investment

**buy->assignment** (string)  
Assignment of short option holding

**buy->contribution** (string)  
Inflow of assets into a tax-advantaged account

**buy->buy** (string)  
Purchase to open or increase a position

**buy->buy to cover** (string)  
Purchase to close a short position

**buy->dividend reinvestment** (string)  
Purchase using proceeds from a cash dividend

**buy->interest reinvestment** (string)  
Purchase using proceeds from a cash interest payment

**buy->long-term capital gain reinvestment** (string)  
Purchase using long-term capital gain cash proceeds

**buy->short-term capital gain reinvestment** (string)  
Purchase using short-term capital gain cash proceeds

**sell** (string)  
Selling an investment

**sell->distribution** (string)  
Outflow of assets from a tax-advantaged account

**sell->exercise** (string)  
Exercise of an option or warrant contract

**sell->sell** (string)  
Sell to close or decrease an existing holding

**sell->sell short** (string)  
Sell to open a short position

**cancel** (string)  
A cancellation of a pending transaction

**cash** (string)  
Activity that modifies a cash position

**cash->account fee** (string)  
Fees paid for account maintenance

**cash->contribution** (string)  
Inflow of assets into a tax-advantaged account

**cash->deposit** (string)  
Inflow of cash into an account

**cash->dividend** (string)  
Inflow of cash from a dividend

**cash->stock distribution** (string)  
Inflow of stock from a distribution

**cash->interest** (string)  
Inflow of cash from interest

**cash->legal fee** (string)  
Fees paid for legal charges or services

**cash->long-term capital gain** (string)  
Long-term capital gain received as cash

**cash->management fee** (string)  
Fees paid for investment management of a mutual fund or other pooled investment vehicle

**cash->margin expense** (string)  
Fees paid for maintaining margin debt

**cash->non-qualified dividend** (string)  
Inflow of cash from a non-qualified dividend

**cash->non-resident tax** (string)  
Taxes paid on behalf of the investor for non-residency in investment jurisdiction

**cash->pending credit** (string)  
Pending inflow of cash

**cash->pending debit** (string)  
Pending outflow of cash

**cash->qualified dividend** (string)  
Inflow of cash from a qualified dividend

**cash->short-term capital gain** (string)  
Short-term capital gain received as cash

**cash->tax** (string)  
Taxes paid on behalf of the investor

**cash->tax withheld** (string)  
Taxes withheld on behalf of the customer

**cash->transfer fee** (string)  
Fees incurred for transfer of a holding or account

**cash->trust fee** (string)  
Fees related to administration of a trust account

**cash->unqualified gain** (string)  
Unqualified capital gain received as cash

**cash->withdrawal** (string)  
Outflow of cash from an account

**fee** (string)  
Fees on the account, e.g. commission, bookkeeping, options-related.

**fee->account fee** (string)  
Fees paid for account maintenance

**fee->adjustment** (string)  
Increase or decrease in quantity of item

**fee->dividend** (string)  
Inflow of cash from a dividend

**fee->interest** (string)  
Inflow of cash from interest

**fee->interest receivable** (string)  
Inflow of cash from interest receivable

**fee->long-term capital gain** (string)  
Long-term capital gain received as cash

**fee->legal fee** (string)  
Fees paid for legal charges or services

**fee->management fee** (string)  
Fees paid for investment management of a mutual fund or other pooled investment vehicle

**fee->margin expense** (string)  
Fees paid for maintaining margin debt

**fee->non-qualified dividend** (string)  
Inflow of cash from a non-qualified dividend

**fee->non-resident tax** (string)  
Taxes paid on behalf of the investor for non-residency in investment jurisdiction

**fee->qualified dividend** (string)  
Inflow of cash from a qualified dividend

**fee->return of principal** (string)  
Repayment of loan principal

**fee->short-term capital gain** (string)  
Short-term capital gain received as cash

**fee->stock distribution** (string)  
Inflow of stock from a distribution

**fee->tax** (string)  
Taxes paid on behalf of the investor

**fee->tax withheld** (string)  
Taxes withheld on behalf of the customer

**fee->transfer fee** (string)  
Fees incurred for transfer of a holding or account

**fee->trust fee** (string)  
Fees related to administration of a trust account

**fee->unqualified gain** (string)  
Unqualified capital gain received as cash

**transfer** (string)  
Activity that modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer

**transfer->assignment** (string)  
Assignment of short option holding

**transfer->adjustment** (string)  
Increase or decrease in quantity of item

**transfer->exercise** (string)  
Exercise of an option or warrant contract

**transfer->expire** (string)  
Expiration of an option or warrant contract

**transfer->merger** (string)  
Stock exchanged at a pre-defined ratio as part of a merger between companies

**transfer->request** (string)  
Request fiat or cryptocurrency to an address or email

**transfer->send** (string)  
Inflow or outflow of fiat or cryptocurrency to an address or email

**transfer->spin off** (string)  
Inflow of stock from spin-off transaction of an existing holding

**transfer->split** (string)  
Inflow of stock from a forward split of an existing holding

**transfer->trade** (string)  
Trade of one cryptocurrency for another

**transfer->transfer** (string)  
Movement of assets into or out of an account

---


# API - Consent | Plaid Docs

Consent 
========

#### API reference for managing consent 

| Endpoints |  |
| --- | --- |
| [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) | Retrieve consent events |

| See also |  |
| --- | --- |
| [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | Retrieve an Item (includes Item consent details) |

\=\*=\*=\*=

#### /consent/events/get 

#### List a historical log of item consent events 

List a historical log of Item consent events. Consent logs are only available for events occurring on or after November 7, 2024. Up to three years of consent logs will be available via the endpoint.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

```javascript
const request: ConsentEventsGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.consentEventsGet(request);
  const consentEvents = response.data.consent_events;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

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

**consent\_events** (\[object\])  
A list of consent events.

**consent\_events->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.

**consent\_events->created\_at** (string)  
The date and time when the consent event occurred, in ISO 8601 format. Format: date-time

**consent\_events->event\_type** (string)  
A broad categorization of the consent event. Possible values: CONSENT\_GRANTED, CONSENT\_REVOKED, CONSENT\_UPDATED

**consent\_events->event\_code** (string)  
Codes describing the object of a consent event. Possible values: USER\_AGREEMENT, USE\_CASES, DATA\_SCOPES, ACCOUNT\_SCOPES, REVOCATION

**consent\_events->institution\_id** (nullable, string)  
Unique identifier for the institution associated with the Item. Field is null for Items created via Same Day Micro-deposits.

**consent\_events->institution\_name** (nullable, string)  
The full name of the institution associated with the Item. Field is null for Items created via Same Day Micro-deposits.

**consent\_events->initiator** (string)  
The entity that initiated collection of consent. Possible values: PLAID, DATA\_PROVIDER, CUSTOMER, END\_USER

**consent\_events->consented\_use\_cases** (\[string\])  
A list of strings containing the full list of use cases the end user has consented to for the Item. See the full list of use cases.

**consent\_events->consented\_data\_scopes** (\[string\])  
A list of strings containing the full list of data scopes the end user has consented to for the Item. These correspond to consented products; see the full mapping of data scopes and products.

**consent\_events->consented\_accounts** (\[object\])  
An array containing the accounts associated with the Item for which authorizations are granted.

**consent\_events->consented\_accounts->account\_id** (string)  
Plaid’s unique identifier for the account. Like all Plaid identifiers, the account\_id is case sensitive.

**consent\_events->consented\_accounts->mask** (string)  
The last 2-4 alphanumeric characters of an account's official account number

**consent\_events->consented\_accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**consent\_events->consented\_accounts->official\_name** (string)  
The official name of the account as given by the financial institution

**consent\_events->consented\_accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**consent\_events->consented\_accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

```json
{
  "request_id": "m8MDnv9okwxFNBV",
  "consent_events": [
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "event_type": "CONSENT_GRANTED",
      "event_code": "USER_AGREEMENT",
      "institution_id": "ins_123456",
      "institution_name": "Platypus bank",
      "initiator": "END_USER",
      "created_at": "2019-02-15T15:51:39Z",
      "consented_use_cases": [],
      "consented_data_scopes": [],
      "consented_accounts": []
    },
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "event_type": "CONSENT_GRANTED",
      "event_code": "USE_CASES",
      "institution_id": "ins_123456",
      "institution_name": "Platypus bank",
      "initiator": "END_USER",
      "created_at": "2019-02-15T15:52:39Z",
      "consented_use_cases": [
        "Send and receive money",
        "Track and manage your finances"
      ],
      "consented_data_scopes": [],
      "consented_accounts": []
    },
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "event_type": "CONSENT_GRANTED",
      "event_code": "DATA_SCOPES",
      "institution_id": "ins_123456",
      "institution_name": "Platypus bank",
      "initiator": "END_USER",
      "created_at": "2019-02-15T15:52:39Z",
      "consented_use_cases": [],
      "consented_data_scopes": [
        "account_and_balance_info",
        "contact_info",
        "account_and_routing_number"
      ],
      "consented_accounts": []
    },
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "event_type": "CONSENT_GRANTED",
      "event_code": "ACCOUNT_SCOPES",
      "institution_id": "ins_123456",
      "institution_name": "Platypus bank",
      "initiator": "END_USER",
      "created_at": "2019-02-15T15:53:39Z",
      "consented_use_cases": [],
      "consented_data_scopes": [],
      "consented_accounts": [
        {
          "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
          "mask": "0000",
          "name": "Plaid Checking",
          "official_name": "Plaid Gold Standard 0% Interest Checking",
          "type": "depository",
          "subtype": "checking"
        }
      ]
    },
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "event_type": "CONSENT_REVOKED",
      "event_code": "REVOCATION",
      "institution_id": "ins_123456",
      "institution_name": "Platypus bank",
      "initiator": "END_USER",
      "created_at": "2020-02-20T15:53:39Z",
      "consented_use_cases": [],
      "consented_data_scopes": [],
      "consented_accounts": []
    }
  ]
}
```

---


# API - Overview | Plaid Docs

API Reference 
==============

#### Comprehensive reference for integrating with Plaid API endpoints 

\=\*=\*=\*=

#### API endpoints and webhooks 

For documentation on specific API endpoints and webhooks, use the navigation menu or search.

\=\*=\*=\*=

#### API access 

To gain access to the Plaid API, create an account on the [Plaid Dashboard](https://dashboard.plaid.com) . Once you’ve completed the signup process and acknowledged our terms, we’ll provide a live `client_id` and `secret` via the Dashboard.

\=\*=\*=\*=

#### API protocols and headers 

The Plaid API is JSON over HTTP. Requests are POST requests, and responses are JSON, with errors indicated in response bodies as `error_code` and `error_type` (use these in preference to HTTP status codes for identifying application-level errors). All responses come as standard JSON, with a small subset returning binary data where appropriate. The Plaid API is served over HTTPS TLS v1.2 to ensure data privacy; HTTP and HTTPS with TLS versions other than 1.2 are not supported. Clients must use an up to date root certificate bundle as the only TLS verification path; certificate pinning should never be used. All requests must include a `Content-Type` of `application/json` and the body must be valid JSON.

Almost all Plaid API endpoints require a `client_id` and `secret`. These may be sent either in the request body or in the headers `PLAID-CLIENT-ID` and `PLAID-SECRET`.

Every Plaid API response includes a `request_id`, either in the body or (in the case of endpoints that return binary data, such as [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) ) in the response headers. For faster support, include the `request_id` when contacting support regarding a specific API call.

\=\*=\*=\*=

#### API host 

```undefined
https://sandbox.plaid.com (Sandbox)
https://production.plaid.com (Production)
```

Plaid has two environments: Sandbox and Production. Items cannot be moved between environments. The Sandbox environment supports only test Items. You can [request Production API access](https://dashboard.plaid.com/overview/production) via the Dashboard.

\=\*=\*=\*=

#### API status and incidents 

API status is available at [status.plaid.com](https://status.plaid.com) .

API status and incidents are also available programmatically via the following endpoints:

*   [https://status.plaid.com/api/v2/status.json](https://status.plaid.com/api/v2/status.json) for current status
*   [https://status.plaid.com/api/v2/incidents.json](https://status.plaid.com/api/v2/incidents.json) for current and historical incidents

For a complete list of all API status information available programmatically, as well as more information on using these endpoints, see the [Atlassian Status API documentation](https://status.atlassian.com/api) .

For information on institution-specific status, see [Troubleshooting institution status](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-institution-status) .

\=\*=\*=\*=

#### Storing API data 

Any token returned by the API is sensitive and should be stored securely. Except for the `public_token` and `link_token`, all Plaid tokens are long-lasting and should never be exposed on the client side. Consumer data obtained from the Plaid API is sensitive information and should be managed accordingly. For guidance and best practices on how to store and handle sensitive data, see the [Open Finance Security Data Standard](https://ofdss.org/#documents) .

Identifiers used by the Plaid API that do not contain consumer data and are not keys or tokens are designed for usage in less sensitive contexts. The most common of these identifiers are the `account_id`, `item_id`, `link_session_id`, and `request_id`. These identifiers are commonly used for logging and debugging purposes.

\=\*=\*=\*=

#### API field formats 

##### Strings 

Many string fields returned by Plaid APIs are reported exactly as returned by the financial institution. For this reason, Plaid does not have maximum length limits or standardized formats for strings returned by the API. In practice, field lengths of 280 characters will generally be adequate for storing returned strings, although Plaid does not guarantee this as a maximum string length.

##### Numbers and money 

Plaid returns all currency values as decimal values in dollars (or the equivalent for the currency being used), rather than as integers. In some cases, it may be possible for a money value returned by the Plaid API to have more than two digits of precision -- this is common, for example, when reporting crypto balances.

\=\*=\*=\*=

#### OpenAPI definition file 

OpenAPI is a standard format for describing RESTful APIs that allows those APIs to be integrated with tools for a wide variety of applications, including testing, client library generation, IDE integration, and more. The Plaid API is specified in our [Plaid OpenAPI GitHub repo](https://github.com/plaid/plaid-openapi) .

\=\*=\*=\*=

#### Postman collection 

The [Postman collection](https://github.com/plaid/plaid-postman) is a convenient tool for exploring Plaid API endpoints without writing code. The Postman collection provides pre-formatted requests for almost all of Plaid's API endpoints. All you have to do is fill in your API keys and any arguments. To get started, check out the [Plaid Postman Collection Quickstart](https://github.com/plaid/plaid-postman) on GitHub.

\=\*=\*=\*=

#### Client libraries 

See the [client libraries](https://plaid.com/docs/api/libraries/index.html.md) page for more information on Plaid's client libraries.

---


# API - Items | Plaid Docs

Items 
======

#### API reference for managing Items 

| Endpoints |  |
| --- | --- |
| [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | Retrieve an Item |
| [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) | Remove an Item |
| [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) | Update a webhook URL |
| [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) | Exchange a public token from Link for an access token |
| [/item/access\_token/invalidate](https://plaid.com/docs/api/items/index.html.md#itemaccess_tokeninvalidate) | Rotate an access token without deleting the Item |

| See also |  |
| --- | --- |
| [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Create a test Item (Sandbox only) |
| [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Force an Item into an error state (Sandbox only) |
| [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | Set Auth verification status (Sandbox only) |
| [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) | Fire a test webhook (Sandbox only) |

| Webhooks |  |
| --- | --- |
| [ERROR](https://plaid.com/docs/api/items/index.html.md#error) | Item has entered an error state |
| [LOGIN\_REPAIRED](https://plaid.com/docs/api/items/index.html.md#login_repaired) | Item has healed from `ITEM_LOGIN_REQUIRED` without update mode |
| [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) | New account detected for an Item |
| [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) | Item access is about to expire (US/CA) or end |
| [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) | Item access is about to expire (UK/EU) |
| [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) | The user has revoked access to an Item |
| [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_account_revoked) | The user has revoked access to an account |
| [WEBHOOK\_UPDATE\_ACKNOWLEDGED](https://plaid.com/docs/api/items/index.html.md#webhook_update_acknowledged) | Item webhook URL updated |

### Token exchange flow 

Many API calls to Plaid product endpoints require an `access_token`. An `access_token` corresponds to an _Item_, which is a login at a financial institution. To obtain an `access_token`:

1.  Obtain a `link_token` by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
2.  Initialize Link by passing in the `link_token`. When your user completes the Link flow, Link will pass back a `public_token` via the [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) , or, if using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) , via a webhook. For more information on initializing and receiving data back from Link, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
3.  Exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .  
    

The `access_token` can then be used to call Plaid endpoints and obtain information about an Item.

In addition to the primary flow, several other token flows exist. The [Link update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow allows you to update an `access_token` that has stopped working. The Sandbox testing environment also offers the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint, which allows you to create a `public_token` without using Link. The [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) and [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) flows provide the `public_token` via the backend rather than using the frontend `onSuccess` callback.

### Endpoints 

\=\*=\*=\*=

#### /item/get 

#### Retrieve an Item 

Returns information about the status of an Item.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

```javascript
const request: ItemGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.itemGet(request);
  const item = response.data.item;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**item** (object)  
Metadata about the Item

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**item->created\_at** (string)  
The date and time when the Item was created, in ISO 8601 format. Format: date-time

**item->consented\_use\_cases** (\[string\])  
A list of use cases that the user has consented to for the Item via Data Transparency Messaging. You can see the full list of use cases or update the list of use cases to request at any time via the Link Customization section of the Plaid Dashboard.

**item->consented\_data\_scopes** (\[string\])  
A list of data scopes that the user has consented to for the Item via Data Transparency Messaging. These are based on the consented\_products; see the full mapping of data scopes and products. Possible values: account\_and\_balance\_info, contact\_info, account\_and\_routing\_numbers, transactions, credit\_and\_loans, investments, bank\_statements, risk\_info

**status** (nullable, object)  
Information about the last successful and failed transactions update for the Item.

**status->investments** (nullable, object)  
Information about the last successful and failed investments update for the Item.

**status->investments->last\_successful\_update** (nullable, string)  
ISO 8601 timestamp of the last successful investments update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update. Format: date-time

**status->investments->last\_failed\_update** (nullable, string)  
ISO 8601 timestamp of the last failed investments update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update. Format: date-time

**status->transactions** (nullable, object)  
Information about the last successful and failed transactions update for the Item.

**status->transactions->last\_successful\_update** (nullable, string)  
ISO 8601 timestamp of the last successful transactions update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update. This field does not reflect transactions updates performed by non-Transactions products (e.g. Signal). Format: date-time

**status->transactions->last\_failed\_update** (nullable, string)  
ISO 8601 timestamp of the last failed transactions update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update. This field does not reflect transactions updates performed by non-Transactions products (e.g. Signal). Format: date-time

**status->last\_webhook** (nullable, object)  
Information about the last webhook fired for the Item.

**status->last\_webhook->sent\_at** (nullable, string)  
ISO 8601 timestamp of when the webhook was fired. Format: date-time

**status->last\_webhook->code\_sent** (nullable, string)  
The last webhook code sent.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "item": {
    "created_at": "2019-01-22T04:32:00Z",
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "institution_name": "First Platypus Bank",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "update_type": "background",
    "webhook": "https://plaid.com/example/hook",
    "auth_method": null,
    "consented_products": [
      "identity",
      "transactions"
    ],
    "consented_data_scopes": [
      "account_and_balance_info",
      "contact_info",
      "transactions"
    ],
    "consented_use_cases": [
      "Verify your account",
      "Track and manage your finances"
    ],
    "consent_expiration_time": "2024-03-16T15:53:00Z"
  },
  "status": {
    "transactions": {
      "last_successful_update": "2019-02-15T15:52:39Z",
      "last_failed_update": "2019-01-22T04:32:00Z"
    },
    "last_webhook": {
      "sent_at": "2019-02-15T15:53:00Z",
      "code_sent": "DEFAULT_UPDATE"
    }
  },
  "request_id": "m8MDnv9okwxFNBV"
}
```

\=\*=\*=\*=

#### /item/remove 

#### Remove an Item 

The [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) endpoint allows you to remove an Item. Once removed, the `access_token`, as well as any processor tokens or bank account tokens associated with the Item, is no longer valid and cannot be used to access any data that was associated with the Item.  
Calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) is a recommended best practice when offboarding users or if a user chooses to disconnect an account linked via Plaid. For subscription products, such as Transactions, Liabilities, and Investments, calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) is required to end subscription billing for the Item, unless the end user revoked permission (e.g. via [https://my.plaid.com/](https://my.plaid.com/) ). For more details, see [Subscription fee model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) .  
In Limited Production, calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) does not impact the number of remaining Limited Production Items you have available.  
Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove access to them specifically using the [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) endpoint.  
Also note that for certain OAuth-based institutions, an Item removed via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) may still show as an active connection in the institution's OAuth permission manager.  
API versions 2019-05-29 and earlier return a `removed` boolean as part of the response.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**reason\_code** (string)  
The reason for removing the item FRAUD\_FIRST\_PARTY: The end user who owns the connected bank account committed fraud FRAUD\_FALSE\_IDENTITY: The end user created the connection using false identity information or stolen credentials FRAUD\_ABUSE: The end user is abusing the client's service or platform through their connected account FRAUD\_OTHER: Other fraud-related reasons involving the end user not covered by the specific fraud categories CONNECTION\_IS\_NON\_FUNCTIONAL: The connection to the end user's financial institution is broken and cannot be restored OTHER: Any other reason for removing the connection not covered by the above categories Possible values: FRAUD\_FIRST\_PARTY, FRAUD\_FALSE\_IDENTITY, FRAUD\_ABUSE, FRAUD\_OTHER, CONNECTION\_IS\_NON\_FUNCTIONAL, OTHER

**reason\_note** (string)  
Additional context or details about the reason for removing the item. Personally identifiable information, such as an email address or phone number, should not be included in the reason\_note. Max length: 512

```javascript
const request: ItemRemoveRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.itemRemove(request);
  // The Item was removed, access_token is now invalid
} catch (error) {
  // handle error
}


// The Item was removed, access_token is now invalid
```

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

```json
{
  "request_id": "m8MDnv9okwxFNBV"
}
```

\=\*=\*=\*=

#### /item/webhook/update 

#### Update Webhook URL 

The POST [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) allows you to update the webhook URL associated with an Item. This request triggers a [WEBHOOK\_UPDATE\_ACKNOWLEDGED](https://plaid.com/docs/api/items/index.html.md#webhook_update_acknowledged) webhook to the newly specified webhook URL.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**webhook** (string)  
The new webhook URL to associate with the Item. To remove a webhook from an Item, set to null.

```javascript
// Update the webhook associated with an Item
const request: ItemWebhookUpdateRequest = {
  access_token: accessToken,
  webhook: 'https://example.com/updated/webhook',
};
try {
  const response = await plaidClient.itemWebhookUpdate(request);
  // A successful response indicates that the webhook has been
  // updated. An acknowledgement webhook will also be fired.
  const item = response.data.item;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": [
      "assets",
      "auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "institution_name": "Royal Bank of Plaid",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "vYK11LNTfRoAMbj"
}
```

\=\*=\*=\*=

#### /item/public\_token/exchange 

#### Exchange public token for an access token 

Exchange a Link `public_token` for an API `access_token`. Link hands off the `public_token` client-side via the `onSuccess` callback once a user has successfully created an Item. The `public_token` is ephemeral and expires after 30 minutes. An `access_token` does not expire, but can be revoked by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) .  
The response also includes an `item_id` that should be stored with the `access_token`. The `item_id` is used to identify an Item in a webhook. The `item_id` can also be retrieved by making an [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) request.

#### 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** (required, string)  
Your public\_token, obtained from the Link onSuccess callback or /sandbox/item/public\_token/create.

```javascript
const request: ItemPublicTokenExchangeRequest = {
  public_token: publicToken,
};
try {
  const response = await plaidClient.itemPublicTokenExchange(request);
  const accessToken = response.data.access_token;
  const itemId = response.data.item_id;
} catch (err) {
  // handle error
}
```

#### Response fields and example 

**access\_token** (string)  
The access token associated with the Item data is being requested for.

**item\_id** (string)  
The item\_id value of the Item associated with the returned access\_token

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /item/access\_token/invalidate 

#### Invalidate access\_token 

By default, the `access_token` associated with an Item does not expire and should be stored in a persistent, secure manner.  
You can use the [/item/access\_token/invalidate](https://plaid.com/docs/api/items/index.html.md#itemaccess_tokeninvalidate) endpoint to rotate the `access_token` associated with an Item. The endpoint returns a new `access_token` and immediately invalidates the previous `access_token`.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

```javascript
// Generate a new access_token for an Item, invalidating the old one
const request: ItemAccessTokenInvalidateRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.itemAccessTokenInvalidate(request);
  // Store the new access_token in a persistent, secure datastore
  const accessToken = response.data.new_access_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**new\_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.

```json
{
  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
  "request_id": "m8MDnv9okwxFNBV"
}
```

### Webhooks 

Webhooks are used to communicate changes to an Item, such as an updated webhook, or errors encountered with an Item. The error typically requires user action to resolve, such as when a user changes their password. All Item webhooks have a `webhook_type` of `ITEM`.

\=\*=\*=\*=

#### ERROR 

Fired when an error is encountered with an Item. The error can be resolved by having the user go through Link’s update mode.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
ERROR

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "ERROR",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": {
    "display_message": "The user’s OAuth connection to this institution has been invalidated.",
    "error_code": "ITEM_LOGIN_REQUIRED",
    "error_code_reason": "OAUTH_INVALID_TOKEN",
    "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
    "error_type": "ITEM_ERROR",
    "status": 400
  },
  "environment": "production"
}
```

\=\*=\*=\*=

#### LOGIN\_REPAIRED 

Fired when an Item has exited the `ITEM_LOGIN_REQUIRED` state without the user having gone through the update mode flow in your app (this can happen if the user completed the update mode in a different app). If you have messaging that tells the user to complete the update mode flow, you should silence this messaging upon receiving the `LOGIN_REPAIRED` webhook.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
LOGIN\_REPAIRED

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "LOGIN_REPAIRED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "environment": "production"
}
```

\=\*=\*=\*=

#### NEW\_ACCOUNTS\_AVAILABLE 

Fired when Plaid detects a new account. Upon receiving this webhook, you can prompt your users to share new accounts with you through [update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) (US/CA only). If the end user has opted not to share new accounts with Plaid via their institution's OAuth settings, Plaid will not detect new accounts and this webhook will not fire. For end user accounts in the EU and UK, upon receiving this webhook, you can prompt your user to re-link their account and then delete the old Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) .

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
NEW\_ACCOUNTS\_AVAILABLE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "NEW_ACCOUNTS_AVAILABLE",
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
  "error": null,
  "environment": "production"
}
```

\=\*=\*=\*=

#### PENDING\_DISCONNECT 

Fired when an Item is expected to be disconnected. The webhook will currently be fired 7 days before the existing Item is scheduled for disconnection. This can be resolved by having the user go through Link’s [update mode](https://plaid.comhttp://plaid.com/docs/link/update-mode/index.html.md) . Currently, this webhook is fired only for US or Canadian institutions; in the UK or EU, you should continue to listed for the [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) webhook instead.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
PENDING\_DISCONNECT

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**reason** (string)  
Reason why the item is about to be disconnected. INSTITUTION\_MIGRATION: The institution is moving to API or to a different integration. For example, this can occur when an institution moves from a non-OAuth integration to an OAuth integration. INSTITUTION\_TOKEN\_EXPIRATION: The consent on an Item associated with a US or CA institution is about to expire. Possible values: INSTITUTION\_MIGRATION, INSTITUTION\_TOKEN\_EXPIRATION

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "PENDING_DISCONNECT",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "reason": "INSTITUTION_MIGRATION",
  "environment": "production"
}
```

\=\*=\*=\*=

#### PENDING\_EXPIRATION 

Fired when an Item’s access consent is expiring in 7 days. This can be resolved by having the user go through Link’s update mode. This webhook is fired only for Items associated with institutions in Europe (including the UK); for Items associated with institutions in the US or Canada, see [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) instead.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
PENDING\_EXPIRATION

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**consent\_expiration\_time** (string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. Format: date-time

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "PENDING_EXPIRATION",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "consent_expiration_time": "2020-01-15T13:25:17.766Z",
  "environment": "production"
}
```

\=\*=\*=\*=

#### USER\_PERMISSION\_REVOKED 

The `USER_PERMISSION_REVOKED` webhook may be fired when an end user has revoked the permission that they previously granted to access an Item. If the end user revoked their permissions through Plaid (such as via the Plaid Portal or by contacting Plaid Support), the webhook will fire. If the end user revoked their permissions directly through the institution, this webhook may not always fire, since some institutions’ consent portals do not trigger this webhook. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the Item. To attempt to restore the Item, it can be sent through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Depending on the exact process the end user used to revoke permissions, it may not be possible to launch update mode for the Item. If you encounter an error when attempting to create a Link token for update mode on an Item with revoked permissions, create a fresh Link token for the user.  
Note that when working with tokenized account numbers with Auth or Transfer, the account number provided by Plaid will no longer work for creating transfers once user permission has been revoked, except for US Bank Items.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
USER\_PERMISSION\_REVOKED

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "USER_PERMISSION_REVOKED",
  "error": {
    "error_code": "USER_PERMISSION_REVOKED",
    "error_message": "the holder of this account has revoked their permission for your application to access it",
    "error_type": "ITEM_ERROR",
    "status": 400
  },
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
  "environment": "production"
}
```

\=\*=\*=\*=

#### USER\_ACCOUNT\_REVOKED 

The `USER_ACCOUNT_REVOKED` webhook is fired when an end user has revoked access to their account on the Data Provider's portal. This webhook is currently sent only for Chase and PNC Items, but may be sent in the future for other financial institutions that allow account-level permissions revocation through their portals. Upon receiving this webhook, it is recommended to delete any Plaid-derived data you have stored that is associated with the revoked account.  
If you are using Auth and receive this webhook, this webhook indicates that the TAN associated with the revoked account is no longer valid and cannot be used to create new transfers. You should not create new ACH transfers for the account that was revoked until access has been re-granted.  
You can request the user to re-grant access to their account by sending them through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Alternatively, they may re-grant access directly through the Data Provider's portal.  
After the user has re-granted access, Auth customers should call the auth endpoint again to obtain the new TAN.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
USER\_ACCOUNT\_REVOKED

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**account\_id** (string)  
The external account ID of the affected account

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "USER_ACCOUNT_REVOKED",
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
  "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
  "environment": "production"
}
```

\=\*=\*=\*=

#### WEBHOOK\_UPDATE\_ACKNOWLEDGED 

Fired when an Item's webhook is updated. This will be sent to the newly specified webhook.

#### Properties 

**webhook\_type** (string)  
ITEM

**webhook\_code** (string)  
WEBHOOK\_UPDATE\_ACKNOWLEDGED

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**new\_webhook\_url** (string)  
The new webhook URL

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ITEM",
  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_webhook_url": "https://plaid.com/example/webhook",
  "environment": "production"
}
```

---


# API - Look up Dashboard users | Plaid Docs

Dashboard User Audit API 
=========================

#### API reference for viewing Dashboard users for Monitor and Beacon 

These endpoints are used to look up a Dashboard user, as referenced in an `audit_trail` object from the [Monitor](https://plaid.com/docs/api/products/monitor/index.html.md) or [Beacon](https://plaid.com/docs/api/products/beacon/index.html.md) APIs.

| Endpoints |  |
| --- | --- |
| [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about Dashboard user |
| [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List Dashboard users |

\=\*=\*=\*=

#### /dashboard\_user/get 

#### Retrieve a dashboard user 

The [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) endpoint provides details (such as email address) about a specific Dashboard user based on the `dashboard_user_id` field, which is returned in the `audit_trail` object of certain Monitor and Beacon endpoints. This can be used to identify the specific reviewer who performed a Dashboard action.

#### Request fields 

**dashboard\_user\_id** (required, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

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

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

```javascript
const request: DashboardUserGetRequest = {
  dashboard_user_id: 'usr_1SUuwqBdK75GKi',
};


try {
  const response = await client.dashboardUserGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**status** (string)  
The current status of the user. Possible values: invited, active, deactivated

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "54350110fedcbaf01234ffee",
  "created_at": "2020-07-24T03:26:02Z",
  "email_address": "user@example.com",
  "status": "active",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /dashboard\_user/list 

#### List dashboard users 

The [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) endpoint provides details (such as email address) all Dashboard users associated with your account. This can use used to audit or track the list of reviewers for Monitor, Beacon, and Identity Verification products.

#### Request fields 

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

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

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
try {
  const response = await client.dashboardUserList({});
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**dashboard\_users** (\[object\])  
List of dashboard users

**dashboard\_users->id** (string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**dashboard\_users->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**dashboard\_users->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**dashboard\_users->status** (string)  
The current status of the user. Possible values: invited, active, deactivated

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "dashboard_users": [
    {
      "id": "54350110fedcbaf01234ffee",
      "created_at": "2020-07-24T03:26:02Z",
      "email_address": "user@example.com",
      "status": "active"
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

---


# API - Libraries | Plaid Docs

Libraries 
==========

#### Learn about libraries and SDKs to easily integrate with the Plaid APIs 

All libraries for Plaid are listed below. If you've built anything that you'd be willing to share with the Plaid community, please let us know and we'll link to it here!

#### Client libraries 

Plaid offers official API libraries for different programming languages, which are regularly updated for breaking and non-breaking API changes. These client libraries are generated from our [OpenAPI file](https://github.com/plaid/plaid-openapi) .

[(An image of "Node logo")Nodeplaid-node](https://github.com/plaid/plaid-node) [(An image of "Python logo")Pythonplaid-python](https://github.com/plaid/plaid-python) [(An image of "Ruby logo")Rubyplaid-ruby](https://github.com/plaid/plaid-ruby) [(An image of "Java logo")Javaplaid-java](https://github.com/plaid/plaid-java) [(An image of "Go logo")Goplaid-go](https://github.com/plaid/plaid-go)

#### Community libraries 

Explore some of the community-supported libraries available for Plaid listed below. If you built your own library, please reach out to our [Support team](https://dashboard.plaid.com/support/new) to add it to this list! The best way to create your own library is by using the [Plaid OpenAPI file](https://github.com/plaid/plaid-openapi) .

Note that community libraries are not officially supported by Plaid. Plaid cannot provide assistance with using these libraries or guarantee that they will be kept up-to-date with all the changes needed to support the latest modifications to the Plaid API.

[Elixirby @tylerwray](https://github.com/tylerwray/elixir-plaid) [Elixirby @wfgilman](https://github.com/wfgilman/plaid-elixir) [.NETGoing.Plaid, by @viceroypenguin](https://github.com/viceroypenguin/Going.Plaid.NET) [Nodeplaid-fetch, by @heysanil. For Vercel Edge Runtime environments that don't support Axios middleware.](https://github.com/heysanil/plaid-fetch)

#### Link client SDKs 

For information on Plaid's front-end SDKs for web and mobile, see [Link](https://plaid.com/docs/link/index.html.md) .

To learn more about installing and using Link SDKs, check out the docs pages for Link on [JavaScript and React (web)](https://plaid.com/docs/link/web/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , and [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) .

Note that libraries marked as (community) are not officially supported by Plaid. Plaid cannot provide assistance with using these libraries or guarantee that they will be kept up-to-date with all the changes needed to support the latest modifications to the Plaid API.

[(An image of "iOS logo")iOSplaid-link-ios](https://github.com/plaid/plaid-link-ios) [(An image of "Android logo")Androidplaid-link-android](https://github.com/plaid/plaid-link-android) [(An image of "React logo")Reactreact-plaid-link](https://github.com/plaid/react-plaid-link) [(An image of "React Native logo")React Nativereact-native-plaid-link-sdk](https://github.com/plaid/react-native-plaid-link-sdk) [JavaScriptWeb](https://plaid.com/docs/link/web/index.html.md) [Vue by Jeroen Claessens (community)](https://github.com/jclaessens97/vue-plaid-link) [Flutter (mobile)by @jorgefspereira (community)](https://github.com/jorgefspereira/plaid_flutter) [Flutter UniversalBased on Flutter (mobile), adds Flutter Desktop support. By @maxintapp (community)](https://github.com/maxint-app/plaid_universal/) [SolidJS by @thedanchez (community)](https://github.com/dsnchz/solid-plaid-link)

#### Quickstart & example apps 

For a listing of Plaid sample apps, see the [Resources page](https://plaid.com/docs/resources/index.html.md#sample-apps) .

---


# API - Link | Plaid Docs

Link endpoints 
===============

#### API reference for Link tokens and webhooks 

This page covers the backend flow for creating and managing Link tokens. For the Link frontend, see [Link docs](https://plaid.com/docs/link/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) | Create a token for initializing a Link session |
| [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) | Get the public token and other details about a completed Link session |

| See also |  |
| --- | --- |
| [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) | Exchange a public token for an access token |
| [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Create a public token without the Link flow (Sandbox only) |
| [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Force an Item into an error state (Sandbox only) |
| [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) | Create a session (Layer only) |

| Webhooks |  |
| --- | --- |
| [ITEM\_ADD\_RESULT](https://plaid.com/docs/api/link/index.html.md#item_add_result) | An Item was added during a Link session |
| [EVENTS](https://plaid.com/docs/api/link/index.html.md#events) | Events were received from a Hosted Link session |
| [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) | The user has completed a Link session |

### Endpoints 

\=\*=\*=\*=

#### /link/token/create 

#### Create Link Token 

The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) 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](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) as part of the main Link flow. For more details, see the [Link flow overview](https://plaid.com/docs/link/index.html.md#link-flow-overview) .  
A `link_token` generated by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is also used to initialize other Link flows, such as the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow for tokens with expired credentials, or the Identity Verification flow.

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

**client\_name** (required, string)  
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. Min length: 1

**language** (required, string)  
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')Hindi ('hi')Italian ('it')Latvian ('lv')Lithuanian ('lt')Norwegian ('no')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. Min length: 1

**country\_codes** (required, \[string\])  
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 https://plaid.com/global/. By default, access is granted to US and CA. For Production or Limited Production access to other countries, contact Sales or your account manager. 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, Automated Micro-deposits, or Database Auth, country\_codes must be set to \['US'\]. Min items: 1 Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FI

**user** (object)  
An object specifying information about the end user who will be linking their account. Required if user\_id isn't included.

**user->client\_user\_id** (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. Min length: 1

**user->legal\_name** (string)  
The user's full legal name, used for micro-deposit based verification flows. For a small number of customers on legacy flows, providing this field is required to enable micro-deposit-based flows. For all other customers, this field is optional. Providing the user's name in this field when using micro-deposit-based verification will streamline the end user experience, as the user will not be prompted to enter their name during the Link flow; Plaid will use the provided legal name instead.

**user->name** (object)  
The user's full name. Optional if using the Identity Verification product; if not using Identity Verification, this field is not allowed. Users will not be asked for their name when this field is provided.

**user->name->given\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->phone\_number** (string)  
The user's phone number in E.164 format. If supplied, will be used when applicable to prefill phone number fields in Link for the returning user flow and the Identity Verification flow. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**user->email\_address** (string)  
The user's email address. Can be used to prefill Link fields when used with Identity Verification.

**user->date\_of\_birth** (string)  
To be provided in the format "yyyy-mm-dd". Can be used to prefill Link fields when used with Identity Verification. Format: date

**user->address** (object)  
The user's address. Used only for Identity Verification and the Identity Match in Link workflows. If provided for Identity Verification, the user will not be shown fields to enter their address in the Identity Verification flow. If provided for Identity Match, the provided data will be used to match against the user's address. May be omitted, but if not omitted, all fields marked as required must be provided.

**user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (required, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->id\_number** (object)  
The user's ID number. Used only for Identity Verification. If provided, the user will not be shown fields to enter their ID number in the Identity Verification flow. May be omitted, but if not omitted, all fields marked as required must be provided.

**user->id\_number->value** (required, string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (required, string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**products** (\[string\])  
List of Plaid product(s) you wish to use. If launching Link in update mode, should be omitted (unless you are using update mode to add Income or Assets to an Item); required otherwise. 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\_reports is required and must be included in the products array. The products specified here will determine which institutions 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. To maximize the number of institutions available, initialize Link with the minimal product set required for your use case. Additional products can be included via the optional\_products or required\_if\_supported\_products fields. Products can also be initialized by calling the 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. 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. Possible values: assets, auth, beacon, employment, identity, income\_verification, identity\_verification, investments, liabilities, payment\_initiation, standing\_orders, signal, statements, transactions, transfer, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, protect\_linked\_bank

**required\_if\_supported\_products** (\[string\])  
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. Possible values: auth, identity, investments, liabilities, transactions, signal, statements, protect\_linked\_bank

**optional\_products** (\[string\])  
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. Possible values: auth, identity, investments, liabilities, signal, statements, transactions

**additional\_consented\_products** (\[string\])  
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 or required\_if\_supported\_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. Possible values: auth, balance\_plus, identity, investments, liabilities, transactions, signal

**webhook** (string)  
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\_token** (string)  
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 (manual) Micro-deposit flow, or (optionally) when initializing Link for a returning user as part of the Transfer UI flow. Min length: 1

**link\_customization\_name** (string)  
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.

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

**android\_package\_name** (string)  
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\_data** (object)  
A map containing data used to highlight institutions in Link.

**institution\_data->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)  
By default, Link will provide limited account filtering: it will only display Institutions that are compatible with all products supplied in the products parameter of /link/token/create, and, if auth is specified in the products array, will also filter out accounts other than checking, savings, and cash management accounts on the Account Select pane. You can further limit the accounts shown in Link by using account\_filters to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. This filtering applies to both the Account Select view (if enabled) and the Institution Select view. Institutions that do not support the selected subtypes will be omitted from Link. To indicate that all subtypes should be shown, use the value "all". If the account\_filters filter is used, any account type for which a filter is not specified will be entirely omitted from Link. For a full list of valid types and subtypes, see the Account schema. The filter may or may not impact the list of accounts shown by the institution in the OAuth account selection flow, depending on the specific institution. If the user selects excluded account subtypes in the OAuth flow, these accounts will not be added to the Item. If the user selects only excluded account subtypes, the link attempt will fail and the user will be prompted to try again.

**account\_filters->depository** (object)  
A filter to apply to depository-type accounts

**account\_filters->depository->account\_subtypes** (required, \[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. Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all

**account\_filters->credit** (object)  
A filter to apply to credit-type accounts

**account\_filters->credit->account\_subtypes** (required, \[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. Possible values: credit card, paypal, all

**account\_filters->loan** (object)  
A filter to apply to loan-type accounts

**account\_filters->loan->account\_subtypes** (required, \[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. Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all

**account\_filters->investment** (object)  
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).

**account\_filters->investment->account\_subtypes** (required, \[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. Possible values: 529, 401a, 401k, 403B, 457b, brokerage, cash isa, crypto exchange, education savings account, fixed annuity, gic, health reimbursement arrangement, hsa, ira, isa, keogh, lif, life insurance, lira, lrif, lrsp, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other annuity, other insurance, pension, prif, profit sharing plan, qshr, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, sep ira, simple ira, sipp, stock plan, tfsa, trust, ugma, utma, variable annuity, all

**account\_filters->other** (object)  
A filter to apply to other-type accounts

**account\_filters->other->account\_subtypes** (required, \[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. Possible values: other, all

**eu\_config** (object)  
Configuration parameters for EU flows

**eu\_config->headless** (boolean)  
If true, open Link without an initial UI. Defaults to false.

**institution\_id** (string)  
Used for certain Europe-only configurations, as well as certain legacy use cases in other regions.

**payment\_initiation** (object)  
Specifies options for initializing Link for use with the Payment Initiation (Europe) product. This field is required if payment\_initiation is included in the products array. Either payment\_id or consent\_id must be provided.

**payment\_initiation->payment\_id** (string)  
The payment\_id provided by the /payment\_initiation/payment/create endpoint.

**payment\_initiation->consent\_id** (string)  
The consent\_id provided by the /payment\_initiation/consent/create endpoint.

**income\_verification** (object)  
Specifies options for initializing Link for use with the Income product. This field is required if income\_verification is included in the products array.

**income\_verification->asset\_report\_id** (string)  
The asset\_report\_id of an asset report associated with the user, as provided by /asset\_report/create. Providing an asset\_report\_id is optional and can be used to verify the user through a streamlined flow. If provided, the bank linking flow will be skipped.

**income\_verification->access\_tokens** (\[string\])  
An array of access tokens corresponding to Items that a user has previously connected with. Data from these institutions will be cross-referenced with document data received during the Document Income flow to help verify that the uploaded documents are accurate. If the transactions product was not initialized for these Items during link, it will be initialized after this Link session. This field should only be used with the payroll income source type.

**income\_verification->income\_source\_types** (\[string\])  
The types of source income data that users will be permitted to share. Options include bank and payroll. Currently you can only specify one of these options. Possible values: bank, payroll

**income\_verification->bank\_income** (object)  
Specifies options for initializing Link for use with Bank Income. This field is required if income\_verification is included in the products array and bank is specified in income\_source\_types.

**income\_verification->bank\_income->days\_requested** (required, integer)  
The number of days of data to request for the Bank Income product Minimum: 1 Maximum: 731

**income\_verification->bank\_income->enable\_multiple\_items** (deprecated, boolean)  
Whether to enable multiple Items to be added in the Link session. This setting is deprecated and has been replaced by the more general enable\_multi\_item\_link setting, which supports all products. Default: false

**income\_verification->payroll\_income** (object)  
Specifies options for initializing Link for use with Payroll Income (including Document Income). Further customization options for Document Income, such as customizing which document types may be uploaded, are also available via the Link Customization pane in the Dashboard. (Requires Production enablement.)

**income\_verification->payroll\_income->flow\_types** (\[string\])  
The types of payroll income verification to enable for the Link session. If none are specified, then users will see both document and digital payroll income. Possible values: payroll\_digital\_income, payroll\_document\_income

**income\_verification->payroll\_income->is\_update\_mode** (boolean)  
An identifier to indicate whether the income verification Link token will be used for update mode. This field is only relevant for participants in the Payroll Income Refresh beta. Default: false

**income\_verification->payroll\_income->item\_id\_to\_update** (string)  
Uniquely identify a payroll income Item to update with. This field is only relevant for participants in the Payroll Income Refresh beta.

**income\_verification->payroll\_income->parsing\_config** (\[string\])  
The types of analysis to enable for document uploads. If this field is not provided, then docs will undergo OCR parsing only. Possible values: ocr, risk\_signals

**income\_verification->stated\_income\_sources** (\[object\])  
A list of user stated income sources

**income\_verification->stated\_income\_sources->employer** (string)  
The employer corresponding to an income source specified by the user

**income\_verification->stated\_income\_sources->category** (string)  
The income category for a specified income source Possible values: OTHER, SALARY, UNEMPLOYMENT, CASH, GIG\_ECONOMY, RENTAL, CHILD\_SUPPORT, MILITARY, RETIREMENT, LONG\_TERM\_DISABILITY, BANK\_INTEREST

**income\_verification->stated\_income\_sources->pay\_per\_cycle** (number)  
The income amount paid per cycle for a specified income source Format: double

**income\_verification->stated\_income\_sources->pay\_annual** (number)  
The income amount paid annually for a specified income source Format: double

**income\_verification->stated\_income\_sources->pay\_type** (string)  
The pay type - GROSS, NET, or UNKNOWN for a specified income source Possible values: UNKNOWN, GROSS, NET

**income\_verification->stated\_income\_sources->pay\_frequency** (string)  
The pay frequency of a specified income source Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY

**cra\_options** (object)  
Specifies options for initializing Link for use with Plaid Check products

**cra\_options->days\_requested** (required, integer)  
The number of days of history to include in Plaid Check products. Maximum is 731; minimum is 180. If a value lower than 180 is provided, a minimum of 180 days of history will be requested. Maximum: 731

**cra\_options->days\_required** (integer)  
The minimum number of days of data required for the report to be successfully generated. Maximum: 184

**cra\_options->client\_report\_id** (string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**cra\_options->partner\_insights** (object)  
Specifies options for initializing Link for use with the Credit Partner Insights product.

**cra\_options->partner\_insights->prism\_products** (deprecated, \[string\])  
The specific Prism products to return. If none are passed in, then all products will be returned. Possible values: insights, scores

**cra\_options->partner\_insights->prism\_versions** (object)  
The versions of Prism products to evaluate

**cra\_options->partner\_insights->prism\_versions->firstdetect** (string)  
The version of Prism FirstDetect. If not specified, will default to v3. Possible values: 3, null

**cra\_options->partner\_insights->prism\_versions->detect** (string)  
The version of Prism Detect Possible values: 4, null

**cra\_options->partner\_insights->prism\_versions->cashscore** (string)  
The version of Prism CashScore. If not specified, will default to v3. Possible values: 4, 3, null

**cra\_options->partner\_insights->prism\_versions->extend** (string)  
The version of Prism Extend Possible values: 4, null

**cra\_options->partner\_insights->prism\_versions->insights** (string)  
The version of Prism Insights. If not specified, will default to v3. Possible values: 4, 3, null

**cra\_options->base\_report** (object)  
Specifies options for initializing Link for use with the Base Report product, specifically the client\_report\_id.

**cra\_options->base\_report->client\_report\_id** (string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**cra\_options->base\_report->gse\_options** (object)  
Specifies options for initializing Link to create reports that can be shared with GSEs for mortgage verification.

**cra\_options->base\_report->gse\_options->report\_types** (required, \[string\])  
Specifies which types of reports should be made available to GSEs. Possible values: VOA, EMPLOYMENT\_REFRESH

**cra\_options->base\_report->require\_identity** (boolean)  
Indicates that the report must include identity information. If identity information is not available, the report will fail.

**cra\_options->cashflow\_insights** (object)  
Specifies options for initializing Link for use with the Cashflow Insights product.

**cra\_options->cashflow\_insights->attributes\_version** (string)  
The version of cashflow attributes Possible values: v1.0, v2.0

**consumer\_report\_permissible\_purpose** (string)  
Describes the reason you are generating a Consumer Report for this user. This parameter is required if you want to generate a Consumer Report for the user automatically after the Link session. If you omit this parameter during Link token creation, you can later call the /cra/check\_report/create endpoint to generate a report. 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). EMPLOYMENT: For employment purposes pursuant to FCRA 604(a)(3)(B), including hiring, retention and promotion purposes. 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. Possible values: ACCOUNT\_REVIEW\_CREDIT, ACCOUNT\_REVIEW\_NON\_CREDIT, EMPLOYMENT, EXTENSION\_OF\_CREDIT, LEGITIMATE\_BUSINESS\_NEED\_TENANT\_SCREENING, LEGITIMATE\_BUSINESS\_NEED\_OTHER, WRITTEN\_INSTRUCTION\_PREQUALIFICATION, WRITTEN\_INSTRUCTION\_OTHER

**auth** (object)  
Specifies options for initializing Link for use with the Auth product. This field can be used to enable or disable extended Auth flows for the resulting Link session. Omitting any field will result in a default that can be configured by your account manager. The default behavior described in the documentation is the default behavior that will apply if you have not requested your account manager to apply a different default. If you have enabled the Dashboard Account Verification pane, the settings enabled there will override any settings in this object.

**auth->auth\_type\_select\_enabled** (boolean)  
Specifies whether Auth Type Select is enabled for the Link session, allowing the end user to choose between linking via a credentials-based flow (i.e. Instant Auth, Instant Match, Automated Micro-deposits) or a manual flow that does not require login (all other Auth flows) prior to selecting their financial institution. Default behavior is false.

**auth->automated\_microdeposits\_enabled** (boolean)  
Specifies whether the Link session is enabled for the Automated Micro-deposits flow. Default behavior is false.

**auth->instant\_match\_enabled** (boolean)  
Specifies whether the Link session is enabled for the Instant Match flow. Instant Match is enabled by default. Instant Match can be disabled by setting this field to false.

**auth->same\_day\_microdeposits\_enabled** (boolean)  
Specifies whether the Link session is enabled for the Same Day Micro-deposits flow. Default behavior is false.

**auth->instant\_microdeposits\_enabled** (boolean)  
Specifies whether the Link session is enabled for the Instant Micro-deposits flow. Default behavior for Plaid teams created after November 2023 is false; default behavior for Plaid teams created before that date is true.

**auth->reroute\_to\_credentials** (string)  
Specifies what type of Reroute to Credentials pane should be used in the Link session for the Same Day Micro-deposits flow. Default behavior is OPTIONAL. Possible values: OFF, OPTIONAL, FORCED

**auth->database\_match\_enabled** (deprecated, boolean)  
Database Match has been deprecated and replaced with Database Auth. Use the Account Verification Dashboard to enable Database Auth.

**auth->database\_insights\_enabled** (deprecated, boolean)  
Database Insights has been deprecated and replaced with Database Auth. Use the Account Verification Dashboard to enable Database Auth.

**auth->flow\_type** (deprecated, string)  
This field has been deprecated in favor of auth\_type\_select\_enabled. Possible values: FLEXIBLE\_AUTH

**auth->sms\_microdeposits\_verification\_enabled** (boolean)  
Specifies whether the Link session is enabled for SMS micro-deposits verification. Default behavior is true.

**transfer** (object)  
Specifies options for initializing Link for use with the Transfer product.

**transfer->intent\_id** (string)  
The id returned by the /transfer/intent/create endpoint.

**transfer->authorization\_id** (string)  
The id returned by the /transfer/authorization/create endpoint. Used to indicate Link session to complete required user action in order to make a decision for the authorization. If set, access\_token can be omitted.

**update** (object)  
Specifies options for initializing Link for update mode.

**update->account\_selection\_enabled** (boolean)  
If true, enables update mode with Account Select for institutions in the US and Canada that do not use OAuth, or that use OAuth but do not have their own account selection flow. For institutions in the US that have an OAuth account selection flow (i.e. most OAuth-enabled institutions), update mode with Account Select will always be enabled, regardless of the value of this field. Default: false

**update->user** (boolean)  
If true, a user\_token must also be provided, and Link will open in update mode for the given user. Default: false

**update->item\_ids** (\[string\])  
An array of item\_ids associated with the user to be updated in update mode. If empty or null, this field will default to initializing update mode for the most recent unhealthy Item associated with the user. A user\_token must also be provided to use this field.

**identity\_verification** (object)  
Specifies option for initializing Link for use with the Identity Verification product.

**identity\_verification->template\_id** (required, string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**identity\_verification->gave\_consent** (boolean)  
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes. If gave\_consent is set to true, the accept\_tos step will be marked as skipped and the end user's session will start at the next step requirement. Default: false

**statements** (object)  
Specifies options for initializing Link for use with the Statements product. This field is required for the statements product.

**statements->start\_date** (required, string)  
The start date for statements, in ISO 8601 "YYYY-MM-DD" format, e.g. "2020-10-30". Format: date

**statements->end\_date** (required, string)  
The end date for statements, in ISO 8601 "YYYY-MM-DD" format, e.g. "2020-10-30". You can request up to two years of data. Format: date

**user\_token** (string)  
A user token generated using /user/create. Any Item created during the Link session will be associated with the user.

**investments** (object)  
Configuration parameters for the Investments product

**investments->allow\_unverified\_crypto\_wallets** (boolean)  
If true, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to false.

**investments->allow\_manual\_entry** (boolean)  
If true, allow users to manually enter Investments account and holdings information. Defaults to false.

**investments\_auth** (object)  
Configuration parameters for the Investments Move product

**investments\_auth->manual\_entry\_enabled** (boolean)  
If true, show institutions that use the manual entry fallback flow. Default: false

**investments\_auth->masked\_number\_match\_enabled** (boolean)  
If true, show institutions that use the masked number match fallback flow. Default: false

**investments\_auth->stated\_account\_number\_enabled** (boolean)  
If true, show institutions that use the stated account number fallback flow. Default: false

**hosted\_link** (object)  
Configuration parameters for Hosted Link. To enable the session for Hosted Link, send this object in the request. It can be empty.

**hosted\_link->delivery\_method** (string)  
How Plaid should deliver the Plaid Link session to the customer. Only available to customers enabled for Link Delivery (beta). To request Link Delivery access, contact your account manager. 'sms' will deliver via SMS. Must pass user.phone\_number. 'email' will deliver via email. Must pass user.email\_address. In the Sandbox environment, this field will be ignored; use the Production environment to test Link Delivery instead. Possible values: sms, email

**hosted\_link->completion\_redirect\_uri** (string)  
URI that Hosted Link will redirect to upon completion of the Link flow. This will only occur in Hosted Link sessions, not in other implementation methods.

**hosted\_link->url\_lifetime\_seconds** (integer)  
How many seconds the link will be valid for. Must be positive. Cannot be longer than 21 days. The default lifetime is 7 days for links delivered by email, 1 day for links delivered via SMS, and 30 minutes for links not sent via Plaid Link delivery. This parameter will override the value of all three link types.

**hosted\_link->is\_mobile\_app** (boolean)  
This indicates whether the client is opening hosted Link in a mobile app in an out of process web view (OOPWV) (i.e., an AsWebAuthenticationSession / SFSafariViewController or Android Custom Tab). Default: false

**transactions** (object)  
Configuration parameters for the Transactions product

**transactions->days\_requested** (integer)  
The maximum number of days of transaction history to request for the Transactions product. The more transaction history is requested, the longer the historical update poll will take. The default value is 90 days. If a value under 30 is provided, a minimum of 30 days of history will be requested. Once Transactions has been added to an Item, this value cannot be updated. Customers using Recurring Transactions should request at least 180 days of history for optimal results. Minimum: 1 Maximum: 730 Default: 90

**identity** (object)  
Identity object used to specify document upload

**identity->is\_document\_upload** (boolean)  
Used to specify whether the Link session is Identity Document Upload

**identity->account\_ids** (\[string\])  
An array of account\_ids. Currently can only contain one account\_id. Must be populated if using Document Upload.

**identity->parsing\_configs** (\[string\])  
An array of parsing configurations. Valid parsing configurations are ocr and risk\_signals. If parsing configurations are omitted, defaults to ocr Possible values: ocr, risk\_signals

**enable\_multi\_item\_link** (boolean)  
If true, enable linking multiple items in the same Link session. Defaults to false.

**user\_id** (string)  
A unique ID generated by Plaid representing the end user. Typically this ID will come from the /user/create response, when the endpoint is invoked with the PLAID-NEW-USER-API-ENABLED header. Required if the user object isn't included. If this field is included, then the remaining user object fields are ignored.

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**link\_token** (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.

**expiration** (string)  
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. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**hosted\_link\_url** (string)  
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.

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

\=\*=\*=\*=

#### /link/token/get 

#### Get Link Token 

The [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) 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](https://plaid.com/docs/link/hosted-link/index.html.md) and the [Multi-Item Link flow](https://plaid.com/docs/link/multi-item-link/index.html.md) . 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](https://plaid.com/docs/api/link/index.html.md#linktokenget) 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 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.

**link\_token** (required, string)  
A link\_token from a previous invocation of /link/token/create

```javascript
const request: LinkTokenGetRequest = {
  link_token: linkToken,
};
try {
  const response = await plaidClient.linkTokenGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**link\_token** (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** (nullable, string)  
The creation timestamp for the link\_token, in ISO 8601 format. Format: date-time

**expiration** (nullable, string)  
The expiration timestamp for the link\_token, in ISO 8601 format. Format: date-time

**link\_sessions** (\[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\_sessions->link\_session\_id** (string)  
The unique ID for the link session.

**link\_sessions->started\_at** (string)  
The timestamp at which the link session was first started, in ISO 8601 format. Format: date-time

**link\_sessions->finished\_at** (nullable, string)  
The timestamp at which the link session was finished, if available, in ISO 8601 format. Format: date-time

**link\_sessions->on\_success** (deprecated, nullable, 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.

**link\_sessions->on\_success->public\_token** (string)  
Displayed once a user has successfully linked their Item.

**link\_sessions->on\_success->metadata** (nullable, object)  
Displayed once a user has successfully linked their Item.

**link\_sessions->on\_success->metadata->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->on\_success->metadata->institution->name** (string)  
The full institution name, such as 'Wells Fargo'

**link\_sessions->on\_success->metadata->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->on\_success->metadata->accounts** (\[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.

**link\_sessions->on\_success->metadata->accounts->id** (string)  
The Plaid account\_id

**link\_sessions->on\_success->metadata->accounts->name** (string)  
The official account name

**link\_sessions->on\_success->metadata->accounts->mask** (nullable, 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.

**link\_sessions->on\_success->metadata->accounts->type** (string)  
The account type. See the Account schema for a full list of possible values

**link\_sessions->on\_success->metadata->accounts->subtype** (string)  
The account subtype. See the Account schema for a full list of possible values

**link\_sessions->on\_success->metadata->accounts->verification\_status** (nullable, 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.

**link\_sessions->on\_success->metadata->accounts->class\_type** (deprecated, nullable, 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\_sessions->on\_success->metadata->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.

**link\_sessions->on\_success->metadata->transfer\_status** (nullable, 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. Possible values: COMPLETE, INCOMPLETE, null

**link\_sessions->on\_exit** (deprecated, nullable, object)  
An object representing an onExit callback from Link. This field has been deprecated in favor of exit, for improved naming consistency.

**link\_sessions->on\_exit->error** (nullable, 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.

**link\_sessions->on\_exit->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**link\_sessions->on\_exit->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**link\_sessions->on\_exit->error->error\_code\_reason** (nullable, 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.

**link\_sessions->on\_exit->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**link\_sessions->on\_exit->error->display\_message** (nullable, 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.

**link\_sessions->on\_exit->error->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.

**link\_sessions->on\_exit->error->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.

**link\_sessions->on\_exit->error->status** (nullable, 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.

**link\_sessions->on\_exit->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**link\_sessions->on\_exit->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**link\_sessions->on\_exit->metadata** (nullable, object)  
Displayed if a user exits Link without successfully linking an Item.

**link\_sessions->on\_exit->metadata->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->on\_exit->metadata->institution->name** (string)  
The full institution name, such as Wells Fargo

**link\_sessions->on\_exit->metadata->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->on\_exit->metadata->status** (string)  
The point at which the user exited the Link flow. One of the following values.

**link\_sessions->on\_exit->metadata->status->requires\_questions**  
User prompted to answer security questions

**link\_sessions->on\_exit->metadata->status->requires\_selections**  
User prompted to answer multiple choice question(s)

**link\_sessions->on\_exit->metadata->status->requires\_code**  
User prompted to provide a one-time passcode

**link\_sessions->on\_exit->metadata->status->choose\_device**  
User prompted to select a device on which to receive a one-time passcode

**link\_sessions->on\_exit->metadata->status->requires\_credentials**  
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

**link\_sessions->on\_exit->metadata->status->requires\_account\_selection**  
User prompted to select one or more financial accounts to share

**link\_sessions->on\_exit->metadata->status->requires\_oauth**  
User prompted to enter an OAuth flow

**link\_sessions->on\_exit->metadata->status->institution\_not\_found**  
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution

**link\_sessions->on\_exit->metadata->status->institution\_not\_supported**  
User exited the Link flow after discovering their selected institution is no longer supported by Plaid

**link\_sessions->on\_exit->metadata->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.

**link\_sessions->on\_exit->metadata->request\_id** (string)  
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.

**link\_sessions->exit** (nullable, object)  
An object representing an onExit callback from Link.

**link\_sessions->exit->error** (nullable, 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.

**link\_sessions->exit->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**link\_sessions->exit->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**link\_sessions->exit->error->error\_code\_reason** (nullable, 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.

**link\_sessions->exit->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**link\_sessions->exit->error->display\_message** (nullable, 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.

**link\_sessions->exit->error->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.

**link\_sessions->exit->error->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.

**link\_sessions->exit->error->status** (nullable, 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.

**link\_sessions->exit->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**link\_sessions->exit->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**link\_sessions->exit->metadata** (nullable, object)  
Displayed if a user exits Link without successfully linking an Item.

**link\_sessions->exit->metadata->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->exit->metadata->institution->name** (string)  
The full institution name, such as Wells Fargo

**link\_sessions->exit->metadata->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->exit->metadata->status** (string)  
The point at which the user exited the Link flow. One of the following values.

**link\_sessions->exit->metadata->status->requires\_questions**  
User prompted to answer security questions

**link\_sessions->exit->metadata->status->requires\_selections**  
User prompted to answer multiple choice question(s)

**link\_sessions->exit->metadata->status->requires\_code**  
User prompted to provide a one-time passcode

**link\_sessions->exit->metadata->status->choose\_device**  
User prompted to select a device on which to receive a one-time passcode

**link\_sessions->exit->metadata->status->requires\_credentials**  
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

**link\_sessions->exit->metadata->status->requires\_account\_selection**  
User prompted to select one or more financial accounts to share

**link\_sessions->exit->metadata->status->requires\_oauth**  
User prompted to enter an OAuth flow

**link\_sessions->exit->metadata->status->institution\_not\_found**  
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution

**link\_sessions->exit->metadata->status->institution\_not\_supported**  
User exited the Link flow after discovering their selected institution is no longer supported by Plaid

**link\_sessions->exit->metadata->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.

**link\_sessions->exit->metadata->request\_id** (string)  
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.

**link\_sessions->events** (\[object\])  
List of customer-related Link events

**link\_sessions->events->event\_name** (string)  
Event name

**link\_sessions->events->timestamp** (string)  
Timestamp in ISO 8601 format.

**link\_sessions->events->event\_id** (string)  
UUID that can be used to deduplicate events

**link\_sessions->events->event\_metadata** (object)  
Metadata about an event that occurred while the user was going through Link

**link\_sessions->events->event\_metadata->error\_code** (string)  
The error code that the user encountered. Emitted by ERROR, EXIT.

**link\_sessions->events->event\_metadata->error\_message** (string)  
The error message that the user encountered. Emitted by: ERROR, EXIT.

**link\_sessions->events->event\_metadata->error\_type** (string)  
The error type that the user encountered. Emitted by: ERROR, EXIT.

**link\_sessions->events->event\_metadata->exit\_status** (string)  
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.

**link\_sessions->events->event\_metadata->institution\_id** (string)  
The ID of the selected institution. Emitted by: all events.

**link\_sessions->events->event\_metadata->institution\_name** (string)  
The name of the selected institution. Emitted by: all events.

**link\_sessions->events->event\_metadata->institution\_search\_query** (string)  
The query used to search for institutions. Emitted by: SEARCH\_INSTITUTION.

**link\_sessions->events->event\_metadata->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.

**link\_sessions->events->event\_metadata->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.

**link\_sessions->events->event\_metadata->view\_name** (string)  
The name of the view that is being transitioned to. Emitted by: TRANSITION\_VIEW.

**link\_sessions->events->event\_metadata->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.

**link\_sessions->events->event\_metadata->brand\_name** (string)  
The name of the selected brand.

**link\_sessions->events->event\_metadata->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.

**link\_sessions->events->event\_metadata->routing\_number** (string)  
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT\_ROUTING\_NUMBER.

**link\_sessions->events->event\_metadata->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.

**link\_sessions->results** (nullable, object)  
The set of results for a Link session.

**link\_sessions->results->item\_add\_results** (\[object\])  
The set of Item adds for the Link session.

**link\_sessions->results->item\_add\_results->public\_token** (string)  
Returned once a user has successfully linked their Item.

**link\_sessions->results->item\_add\_results->accounts** (\[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.

**link\_sessions->results->item\_add\_results->accounts->id** (string)  
The Plaid account\_id

**link\_sessions->results->item\_add\_results->accounts->name** (string)  
The official account name

**link\_sessions->results->item\_add\_results->accounts->mask** (nullable, 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.

**link\_sessions->results->item\_add\_results->accounts->type** (string)  
The account type. See the Account schema for a full list of possible values

**link\_sessions->results->item\_add\_results->accounts->subtype** (string)  
The account subtype. See the Account schema for a full list of possible values

**link\_sessions->results->item\_add\_results->accounts->verification\_status** (nullable, 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.

**link\_sessions->results->item\_add\_results->accounts->class\_type** (deprecated, nullable, 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\_sessions->results->item\_add\_results->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->results->item\_add\_results->institution->name** (string)  
The full institution name, such as 'Wells Fargo'

**link\_sessions->results->item\_add\_results->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->results->cra\_item\_add\_results** (\[object\])  
The set of Plaid Check Item adds for the Link session.

**link\_sessions->results->cra\_item\_add\_results->item\_id** (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.

**link\_sessions->results->cra\_item\_add\_results->accounts** (\[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.

**link\_sessions->results->cra\_item\_add\_results->accounts->id** (string)  
The Plaid account\_id

**link\_sessions->results->cra\_item\_add\_results->accounts->name** (string)  
The official account name

**link\_sessions->results->cra\_item\_add\_results->accounts->mask** (nullable, 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.

**link\_sessions->results->cra\_item\_add\_results->accounts->type** (string)  
The account type. See the Account schema for a full list of possible values

**link\_sessions->results->cra\_item\_add\_results->accounts->subtype** (string)  
The account subtype. See the Account schema for a full list of possible values

**link\_sessions->results->cra\_item\_add\_results->accounts->verification\_status** (nullable, 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.

**link\_sessions->results->cra\_item\_add\_results->accounts->class\_type** (deprecated, nullable, 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\_sessions->results->cra\_item\_add\_results->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->results->cra\_item\_add\_results->institution->name** (string)  
The full institution name, such as 'Wells Fargo'

**link\_sessions->results->cra\_item\_add\_results->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->results->bank\_income\_results** (\[object\])  
The set of bank income verifications for the Link session.

**link\_sessions->results->bank\_income\_results->status** (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. Possible values: APPROVED, NO\_DEPOSITS\_FOUND, USER\_REPORTED\_NO\_INCOME

**link\_sessions->results->bank\_income\_results->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.

**link\_sessions->results->bank\_income\_results->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->results->bank\_income\_results->institution->name** (string)  
The full institution name, such as 'Wells Fargo'

**link\_sessions->results->bank\_income\_results->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->results->payroll\_income\_results** (\[object\])  
The set of payroll income verifications for the Link session.

**link\_sessions->results->payroll\_income\_results->num\_paystubs\_retrieved** (integer)  
The number of paystubs retrieved from a payroll provider.

**link\_sessions->results->payroll\_income\_results->num\_w2s\_retrieved** (integer)  
The number of W-2s retrieved from a payroll provider.

**link\_sessions->results->payroll\_income\_results->institution** (nullable, object)  
An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be null.

**link\_sessions->results->payroll\_income\_results->institution->name** (string)  
The full institution name, such as 'Wells Fargo'

**link\_sessions->results->payroll\_income\_results->institution->institution\_id** (string)  
The Plaid institution identifier

**link\_sessions->results->document\_income\_results** (nullable, object)  
The details of a document income verification in Link

**link\_sessions->results->document\_income\_results->num\_paystubs\_uploaded** (integer)  
The number of paystubs uploaded by the user.

**link\_sessions->results->document\_income\_results->num\_w2s\_uploaded** (integer)  
The number of w2s uploaded by the user.

**link\_sessions->results->document\_income\_results->num\_bank\_statements\_uploaded** (integer)  
The number of bank statements uploaded by the user.

**link\_sessions->results->document\_income\_results->num\_1099s\_uploaded** (integer)  
The number of 1099s uploaded by the user

**link\_sessions->results->cra\_document\_upload\_results** (nullable, object)  
The details of a document upload CRA session in link

**link\_sessions->results->cra\_document\_upload\_results->num\_bank\_statements\_uploaded** (integer)  
The number of bank statements uploaded by the user.

**link\_sessions->results->protect\_results** (nullable, object)  
Plaid Protect details from the Link session

**link\_sessions->results->protect\_results->event\_id** (string)  
The Plaid Protect event ID representing the completion of the link session.

**link\_sessions->results->protect\_results->trust\_index** (nullable, object)  
Represents a calculate Trust Index Score.

**link\_sessions->results->protect\_results->trust\_index->score** (integer)  
The overall trust index score.

**link\_sessions->results->protect\_results->trust\_index->model** (string)  
The versioned name of the Trust Index model used for scoring.

**link\_sessions->results->protect\_results->trust\_index->subscores** (nullable, object)  
Contains sub-score metadata.

**link\_sessions->results->protect\_results->trust\_index->subscores->device\_and\_connection** (nullable, object)  
Represents Trust Index Subscore.

**link\_sessions->results->protect\_results->trust\_index->subscores->device\_and\_connection->score** (integer)  
The subscore score.

**link\_sessions->results->protect\_results->trust\_index->subscores->bank\_account\_insights** (nullable, object)  
Represents Trust Index Subscore.

**link\_sessions->results->protect\_results->trust\_index->subscores->bank\_account\_insights->score** (integer)  
The subscore score.

**link\_sessions->results->protect\_results->fraud\_attributes** (nullable, object)  
Contains attributes used during a trust index calculation.

**metadata** (object)  
An object specifying the arguments originally provided to the /link/token/create call.

**metadata->initial\_products** (\[string\])  
The products specified in the /link/token/create call. Possible values: assets, auth, employment, identity, income\_verification, identity\_verification, investments, liabilities, payment\_initiation, standing\_orders, transactions, transfer

**metadata->webhook** (nullable, string)  
The webhook specified in the /link/token/create call.

**metadata->country\_codes** (\[string\])  
The country\_codes specified in the /link/token/create call. Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FI

**metadata->language** (nullable, string)  
The language specified in the /link/token/create call.

**metadata->institution\_data** (object)  
A map containing data used to highlight institutions in Link.

**metadata->institution\_data->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.

**metadata->account\_filters** (object)  
The account\_filters specified in the original call to /link/token/create.

**metadata->account\_filters->depository** (object)  
A filter to apply to depository-type accounts

**metadata->account\_filters->depository->account\_subtypes** (\[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. Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all

**metadata->account\_filters->credit** (object)  
A filter to apply to credit-type accounts

**metadata->account\_filters->credit->account\_subtypes** (\[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. Possible values: credit card, paypal, all

**metadata->account\_filters->loan** (object)  
A filter to apply to loan-type accounts

**metadata->account\_filters->loan->account\_subtypes** (\[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. Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all

**metadata->account\_filters->investment** (object)  
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).

**metadata->account\_filters->investment->account\_subtypes** (\[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. Possible values: 529, 401a, 401k, 403B, 457b, brokerage, cash isa, crypto exchange, education savings account, fixed annuity, gic, health reimbursement arrangement, hsa, ira, isa, keogh, lif, life insurance, lira, lrif, lrsp, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other annuity, other insurance, pension, prif, profit sharing plan, qshr, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, sep ira, simple ira, sipp, stock plan, tfsa, trust, ugma, utma, variable annuity, all

**metadata->redirect\_uri** (nullable, string)  
The redirect\_uri specified in the /link/token/create call.

**metadata->client\_name** (nullable, string)  
The client\_name specified in the /link/token/create call.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "created_at": "2024-07-29T20:22:21Z",
  "expiration": "2024-07-29T20:52:22Z",
  "link_sessions": [
    {
      "events": [
        {
          "event_id": "8b2b5d28-79ec-468b-bbce-f8bd34be635a",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "Nnclj9HntPMu5dm"
          },
          "event_name": "HANDOFF",
          "timestamp": "2024-07-29T20:23:59Z"
        },
        {
          "event_id": "12a888e0-da26-4c38-8ded-2992bc78c246",
          "event_metadata": {
            "request_id": "Nnclj9HntPMu5dm"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:59Z"
        },
        {
          "event_id": "6557bdf1-a20a-43b0-8fed-c8b671e2f478",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "sR4EGcU8zniznXi"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:56Z"
        },
        {
          "event_id": "c6745f4c-d8fa-4103-8a65-7b995c60809e",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "4LYDWkxfJ0htDA4"
          },
          "event_name": "SUBMIT_CREDENTIALS",
          "timestamp": "2024-07-29T20:23:55Z"
        },
        {
          "event_id": "2610fa06-e765-4c9e-8948-63048d451dbf",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "4LYDWkxfJ0htDA4"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:23Z"
        },
        {
          "event_id": "54b87deb-60a7-4f50-9326-293840090b72",
          "event_metadata": {
            "institution_id": "ins_20",
            "institution_name": "Citizens Bank",
            "request_id": "FTEFiPeL9OstwL4"
          },
          "event_name": "SELECT_INSTITUTION",
          "timestamp": "2024-07-29T20:23:23Z"
        },
        {
          "event_id": "6b285180-0bac-4ccc-bec0-d4ed75c253d2",
          "event_metadata": {
            "request_id": "FTEFiPeL9OstwL4"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:20Z"
        },
        {
          "event_id": "239a6000-da50-4319-99f7-919378b7db53",
          "event_metadata": {
            "request_id": "WFgwgGivjBbwOb9"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:17Z"
        },
        {
          "event_id": "0a523744-5003-4578-8414-c87e06ef8ca9",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "WFgwgGivjBbwOb9"
          },
          "event_name": "HANDOFF",
          "timestamp": "2024-07-29T20:23:17Z"
        },
        {
          "event_id": "ff44d52a-51ef-4987-b7d0-b6497dfa93cd",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "uqA0Vq8zuKlsB2y"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:23:14Z"
        },
        {
          "event_id": "e0d7c1dc-8e7e-4361-893f-d6c2d2f050ab",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "dTGtMHbK21BLrsp"
          },
          "event_name": "OPEN_OAUTH",
          "timestamp": "2024-07-29T20:22:49Z"
        },
        {
          "event_id": "de87a1c0-666e-4d95-88d8-1163f6bf20f1",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "dTGtMHbK21BLrsp"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:47Z"
        },
        {
          "event_id": "6edc2c59-96cd-4dee-a86b-140ddfd3076e",
          "event_metadata": {
            "institution_id": "ins_127989",
            "institution_name": "Bank of America",
            "request_id": "BxBukZsBEmxZw0I"
          },
          "event_name": "SELECT_INSTITUTION",
          "timestamp": "2024-07-29T20:22:46Z"
        },
        {
          "event_id": "d176ab57-26d2-45ee-a0fe-67daf0cf0cb0",
          "event_metadata": {
            "request_id": "BxBukZsBEmxZw0I"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:43Z"
        },
        {
          "event_id": "b8be9c3d-7ac5-4851-bd92-0638cb63bdeb",
          "event_metadata": {
            "request_id": "UtqR09RKzJ1gcEx"
          },
          "event_name": "SKIP_SUBMIT_PHONE",
          "timestamp": "2024-07-29T20:22:42Z"
        },
        {
          "event_id": "7144cca7-533b-4dfc-81ed-f78a750ba95f",
          "event_metadata": {
            "request_id": "UtqR09RKzJ1gcEx"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:40Z"
        },
        {
          "event_id": "e6a6dcc0-6bbf-4871-8d59-0c3a5eccff53",
          "event_metadata": {
            "request_id": "FTiagIVmxfqbevM"
          },
          "event_name": "TRANSITION_VIEW",
          "timestamp": "2024-07-29T20:22:39Z"
        }
      ],
      "finished_at": "2024-07-29T20:24:05.330312653Z",
      "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46",
      "on_success": {
        "metadata": {
          "accounts": [
            {
              "class_type": null,
              "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX",
              "mask": "0000",
              "name": "Plaid Checking",
              "subtype": "checking",
              "type": "depository",
              "verification_status": null
            },
            {
              "class_type": null,
              "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",
              "mask": "1111",
              "name": "Plaid Saving",
              "subtype": "savings",
              "type": "depository",
              "verification_status": null
            },
            {
              "class_type": null,
              "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93",
              "mask": "9999",
              "name": "Plaid Business Credit Card",
              "subtype": "credit card",
              "type": "credit",
              "verification_status": null
            }
          ],
          "institution": {
            "institution_id": "ins_127989",
            "name": "Bank of America"
          },
          "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46",
          "transfer_status": null
        },
        "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a"
      },
      "results": {
        "item_add_results": [
          {
            "accounts": [
              {
                "class_type": null,
                "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX",
                "mask": "0000",
                "name": "Plaid Checking",
                "subtype": "checking",
                "type": "depository",
                "verification_status": null
              },
              {
                "class_type": null,
                "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR",
                "mask": "1111",
                "name": "Plaid Saving",
                "subtype": "savings",
                "type": "depository",
                "verification_status": null
              },
              {
                "class_type": null,
                "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93",
                "mask": "9999",
                "name": "Plaid Business Credit Card",
                "subtype": "credit card",
                "type": "credit",
                "verification_status": null
              }
            ],
            "institution": {
              "institution_id": "ins_127989",
              "name": "Bank of America"
            },
            "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a"
          },
          {
            "accounts": [
              {
                "class_type": null,
                "id": "qvqrX8gDvxCdyvvgGkKzSNPzDwaQGjFgyQk5Z",
                "mask": "4007",
                "name": "Checking",
                "subtype": "checking",
                "type": "depository",
                "verification_status": null
              }
            ],
            "institution": {
              "institution_id": "ins_20",
              "name": "Citizens Bank"
            },
            "public_token": "public-sandbox-44ba202e-bf6b-45c6-a5ba-d526765626a9"
          }
        ],
        "cra_item_add_results": [],
        "bank_income_results": [],
        "payroll_income_results": [],
        "document_income_results": null,
        "protect_results": null
      },
      "started_at": "2024-07-29T20:22:36.522196741Z"
    }
  ],
  "link_token": "link-sandbox-e7b6956c-1522-4823-85d2-c4ca74251949",
  "metadata": {
    "client_name": "Wonderwallet",
    "country_codes": [
      "US"
    ],
    "initial_products": [
      "transactions"
    ],
    "language": "en",
    "redirect_uri": null,
    "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e"
  },
  "request_id": "Pxpgzy0Wjvn99mY"
}
```

### Webhooks 

\=\*=\*=\*=

#### ITEM\_ADD\_RESULT 

Fired when a user successfully adds a Plaid Item during a Link session when using Hosted Link or Multi-Item Link sessions. Contains the public token for the Item.

#### Properties 

**webhook\_type** (string)  
LINK

**webhook\_code** (string)  
ITEM\_ADD\_RESULT

**link\_session\_id** (string)  
The identifier for the Link session.

**link\_token** (string)  
The link token used to create the Link session.

**public\_token** (string)  
The public token corresponding to the item that was added.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

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

\=\*=\*=\*=

#### EVENTS 

This webhook contains a summary of the events from a Link session and will be fired after the user finishes going through Link. If the user abandons the Link flow (i.e., closes the hosted link webpage or leaves Link open for too long without taking any action), the webhook will be fired 5-15 minutes after the last user interaction. A single Link session may occasionally generate multiple `EVENTS` webhooks. If this occurs, the new webhook will contain all previous events for the session, as well as new events that occurred since the previous `EVENTS` webhook was sent. If this occurs, events can be grouped using the `link_session_id` field and, if necessary, de-duplicated using the `event_id` field.  
By default, the `EVENTS` webhook is sent only for sessions where the end user goes through a Hosted Link flow (including Link Recovery flows). If you would like to receive this webhook for sessions not using Hosted Link, contact your Account Manager or Support. This enablement will also cause you to receive the `SESSION_FINISHED` webhook for non-Hosted-Link sessions and to be able to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to receive events data for non-Hosted Link sessions.

#### Properties 

**webhook\_type** (string)  
LINK

**webhook\_code** (string)  
EVENTS

**events** (\[object\])  
The Link events emitted during the Link session

**events->event\_name** (string)  
Event name

**events->timestamp** (string)  
Timestamp in ISO 8601 format.

**events->event\_id** (string)  
UUID that can be used to deduplicate events

**events->event\_metadata** (object)  
Metadata about an event that occurred while the user was going through Link

**events->event\_metadata->error\_code** (string)  
The error code that the user encountered. Emitted by ERROR, EXIT.

**events->event\_metadata->error\_message** (string)  
The error message that the user encountered. Emitted by: ERROR, EXIT.

**events->event\_metadata->error\_type** (string)  
The error type that the user encountered. Emitted by: ERROR, EXIT.

**events->event\_metadata->exit\_status** (string)  
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.

**events->event\_metadata->institution\_id** (string)  
The ID of the selected institution. Emitted by: all events.

**events->event\_metadata->institution\_name** (string)  
The name of the selected institution. Emitted by: all events.

**events->event\_metadata->institution\_search\_query** (string)  
The query used to search for institutions. Emitted by: SEARCH\_INSTITUTION.

**events->event\_metadata->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.

**events->event\_metadata->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.

**events->event\_metadata->view\_name** (string)  
The name of the view that is being transitioned to. Emitted by: TRANSITION\_VIEW.

**events->event\_metadata->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.

**events->event\_metadata->brand\_name** (string)  
The name of the selected brand.

**events->event\_metadata->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.

**events->event\_metadata->routing\_number** (string)  
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT\_ROUTING\_NUMBER.

**events->event\_metadata->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.

**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

```json
{
  "environment": "sandbox",
  "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e",
  "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45",
  "webhook_code": "EVENTS",
  "webhook_type": "LINK",
  "events": [
    {
      "event_id": "9469937a-6fac-40be-9322-f86e8c0b94ed",
      "event_metadata": {
        "request_id": "ClqZyuhovgkaQ3j"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:17:54Z"
    },
    {
      "event_id": "4b2390cf-33a2-4078-b933-62468b9e53a5",
      "event_metadata": {
        "error_code": "INVALID_CREDENTIALS",
        "error_message": "the provided credentials were not correct",
        "error_type": "ITEM_ERROR",
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "ttK0NtGKaVAlbCR"
      },
      "event_name": "ERROR",
      "timestamp": "2024-05-21T00:18:09Z"
    },
    {
      "event_id": "45f76afe-f2aa-495c-a326-f37e043a1ccd",
      "event_metadata": {
        "request_id": "WRJqqeh8Hxife05"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:17:56Z"
    },
    {
      "event_id": "978b772c-f2cc-404f-9449-2113e4671c4f",
      "event_metadata": {
        "error_code": "INVALID_CREDENTIALS",
        "error_message": "the provided credentials were not correct",
        "error_type": "ITEM_ERROR",
        "exit_status": "requires_credentials",
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "u1HcAeiCKtz3qmm"
      },
      "event_name": "EXIT",
      "timestamp": "2024-05-21T00:18:13Z"
    },
    {
      "event_id": "a873db76-aa4e-4a00-9d60-7ae08aa8e63f",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "ttK0NtGKaVAlbCR"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:18:09Z"
    },
    {
      "event_id": "ca85566d-5f32-4716-909f-82f3a0b6160b",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "XRvev3cP9wYUFz5"
      },
      "event_name": "SUBMIT_CREDENTIALS",
      "timestamp": "2024-05-21T00:18:07Z"
    },
    {
      "event_id": "09220752-6b83-407e-baf0-f6228df16ea0",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "WRJqqeh8Hxife05"
      },
      "event_name": "SELECT_INSTITUTION",
      "timestamp": "2024-05-21T00:18:01Z"
    },
    {
      "event_id": "1c75d2ee-19c1-4d1b-8600-7d06cecbb270",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "5vc1IyBHfLkIVFx"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:18:12Z"
    },
    {
      "event_id": "1c9c9059-c065-4362-836a-d9afb91a6125",
      "event_metadata": {
        "request_id": "MlFW5NSWtCs1KLI"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:17:50Z"
    },
    {
      "event_id": "4f381b3f-172b-4bca-9804-c230f8d36a3b",
      "event_metadata": {
        "institution_id": "ins_20",
        "institution_name": "Citizens Bank",
        "request_id": "XRvev3cP9wYUFz5"
      },
      "event_name": "TRANSITION_VIEW",
      "timestamp": "2024-05-21T00:18:02Z"
    },
    {
      "event_id": "dd9d4747-d4da-4c11-88d6-b5a0e96f1886",
      "event_metadata": {
        "request_id": "ClqZyuhovgkaQ3j"
      },
      "event_name": "SKIP_SUBMIT_PHONE",
      "timestamp": "2024-05-21T00:17:55Z"
    }
  ]
}
```

\=\*=\*=\*=

#### 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) or a Multi-Item Link 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 

**webhook\_type** (string)  
LINK

**webhook\_code** (string)  
SESSION\_FINISHED

**status** (string)  
The final status of the Link session. Will always be "SUCCESS" or "EXITED".

**link\_session\_id** (string)  
The identifier for the Link session.

**link\_token** (string)  
The link token used to create the Link session.

**public\_token** (deprecated, string)  
The public token generated by the Link session. This field has been deprecated; please use public\_tokens instead.

**public\_tokens** (\[string\])  
The public tokens generated by the Link session.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```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"
}
```

---


# API - Network | Plaid Docs

Network 
========

#### API reference for the Plaid Network 

| Endpoints |  |
| --- | --- |
| [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) | Check the status of a user in the Plaid Network |

### Endpoints 

\=\*=\*=\*=

#### /network/status/get 

#### Check a user's Plaid Network status 

The [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) endpoint can be used to check whether Plaid has a matching profile for the user. This is useful for determining if a user is eligible for a streamlined experience, such as Layer.  
Note: it is strongly recommended to check for Layer eligibility in the frontend. [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) should only be used for checking Layer eligibility if a frontend check is not possible for your use case. For instructions on performing a frontend eligibility check, see the [Layer documentation](https://plaid.com/docs/layer/index.html.md#integration-overview) .

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

**user** (required, object)  
An object specifying information about the end user for the network status check.

**user->phone\_number** (required, string)  
The user's phone number in E.164 format.

**template\_id** (string)  
The id of a template defined in Plaid Dashboard. This field is used if you have additional criteria that you want to check against (e.g. Layer eligibility).

```javascript
const request: NetworkStatusGetRequest = {
  user: {
    phone_number: '+14155550015',
  },
};
try {
  const response = await plaidClient.networkStatusGet(request);
  const networkStatus = response.data.network_status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**network\_status** (string)  
Enum representing the overall network status of the user. Possible values: UNKNOWN, RETURNING\_USER

**layer** (nullable, object)  
An object representing Layer-related metadata for the requested user.

**layer->eligible** (boolean)  
Indicates if the user is eligible for a Layer session.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "network_status": "RETURNING_USER",
  "request_id": "m8MDnv9okwxFNBV"
}
```

---


# API - OAuth | Plaid Docs

OAuth 
======

#### API reference for Plaid OAuth endpoints 

| Endpoints |  |
| --- | --- |
| [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) | Create or refresh an OAuth access token |
| [/oauth/introspect](https://plaid.com/docs/api/oauth/index.html.md#oauthintrospect) | Get metadata about an OAuth token |
| [/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) | Revoke an OAuth token |

These endpoints are for customers, partners and services that are integrating with Plaid's OAuth service to obtain a token for sharing consumer reports or accessing the Plaid Dashboard or other Plaid services. They are not used for the Plaid Link flow where end users connect their financial institution accounts to Plaid using a bank's OAuth service. If you are a Plaid customer trying to ensure your app supports OAuth-based bank connections, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) instead.

### Endpoints 

\=\*=\*=\*=

#### /oauth/token 

#### Create or refresh an OAuth access token 

[/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) issues an access token and refresh token depending on the `grant_type` provided. This endpoint supports `Content-Type: application/x-www-form-urlencoded` as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification.

#### Request fields 

**grant\_type** (required, string)  
The type of OAuth grant being requested: client\_credentials allows exchanging a client id and client secret for a refresh and access token. refresh\_token allows refreshing an access token using a refresh token. When using this grant type, only the refresh\_token field is required (along with the client\_id and client\_secret). urn:ietf:params:oauth:grant-type:token-exchange allows exchanging a subject token for an OAuth token. When using this grant type, the audience, subject\_token and subject\_token\_type fields are required. These grants are defined in their respective RFCs. refresh\_token and client\_credentials are defined in RFC 6749 and urn:ietf:params:oauth:grant-type:token-exchange is defined in RFC 8693. Possible values: refresh\_token, urn:ietf:params:oauth:grant-type:token-exchange, client\_credentials

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

**client\_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 as either secret or client\_secret.

**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 as either secret or client\_secret.

**scope** (string)  
A JSON string containing a space-separated list of scopes associated with this token, in the format described in https://datatracker.ietf.org/doc/html/rfc6749#section-3.3. Currently accepted values are: user:read allows reading user data. user:write allows writing user data. exchange allows exchanging a token using the urn:plaid:params:oauth:user-token grant type. mcp:dashboard allows access to the MCP dashboard server.

**refresh\_token** (string)  
Refresh token for OAuth

**resource** (string)  
URI of the target resource server

**audience** (string)  
Used when exchanging a token. The meaning depends on the subject\_token\_type.

**subject\_token** (string)  
Token representing the subject. The subject token must be an OAuth refresh token issued from the /oauth/token endpoint. The meaning depends on the subject\_token\_type.

**subject\_token\_type** (string)  
The type of the subject token. urn:plaid:params:tokens:user allows exchanging a Plaid-issued user token for an OAuth token. When using this token type, audience must be the same as the client\_id. subject\_token must be a Plaid-issued user token issued from the /user/create endpoint. urn:plaid:params:oauth:user-token allows exchanging a refresh token for an OAuth token to another client\_id. The other client\_id is provided in audience. subject\_token must be an OAuth refresh token issued from the /oauth/token endpoint. Possible values: urn:plaid:params:tokens:user, urn:plaid:params:oauth:user-token

```javascript
const request = {
    grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
    scope: 'user:read',
    subject_token_type: 'urn:plaid:params:credit:multi-user',
    audience: 'urn:plaid:params:cra-partner:fannie-mae',
    subject_token: userToken
};


try {
    const response = await client.oauthToken(request);
} catch (error) {
    ...
}
```

#### Response fields and example 

**access\_token** (string)  
Access token for OAuth

**refresh\_token** (string)  
Refresh token for OAuth

**token\_type** (string)  
type of token the access token is. Currently it is always Bearer

**expires\_in** (integer)  
time remaining in seconds before expiration

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "access_token": "pda-RDdg0TUCB0FB25_UPIlnhA==",
  "refresh_token": "pdr--viXurkDg88d5zf8m6Wl0g==",
  "expires_in": 900,
  "token_type": "Bearer",
  "request_id": "m8MDqcS6F3lzqvP"
}
```

\=\*=\*=\*=

#### /oauth/introspect 

#### Get metadata about an OAuth token 

[/oauth/introspect](https://plaid.com/docs/api/oauth/index.html.md#oauthintrospect) returns metadata about an access token or refresh token.  
Note: This endpoint supports `Content-Type: application/x-www-form-urlencoded` as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification.

#### Request fields 

**token** (required, string)  
An OAuth token of any type (refresh\_token, access\_token, etc)

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

**client\_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 as either secret or client\_secret.

**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 as either secret or client\_secret.

```javascript
const request = {
  token: accessToken
};


try {
  const response = await client.oauthIntrospect(request);
} catch (error) {
    ...
}
```

#### Response fields and example 

**active** (boolean)  
Boolean indicator of whether or not the presented token is currently active. A true value indicates that the token has been issued, has not been revoked, and is within the time window of validity.

**scope** (string)  
A JSON string containing a space-separated list of scopes associated with this token, in the format described in https://datatracker.ietf.org/doc/html/rfc6749#section-3.3. Currently accepted values are: user:read allows reading user data. user:write allows writing user data. exchange allows exchanging a token using the urn:plaid:params:oauth:user-token grant type. mcp:dashboard allows access to the MCP dashboard server.

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

**exp** (integer)  
Expiration time as UNIX timestamp since January 1 1970 UTC

**iat** (integer)  
Issued at time as UNIX timestamp since January 1 1970 UTC

**sub** (string)  
Subject of the token

**aud** (string)  
Audience of the token

**iss** (string)  
Issuer of the token

**token\_type** (string)  
Type of the token

**user\_id** (string)  
User ID of the token

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "active": true,
  "scope": "user:read user:write exchange",
  "client_id": "68028ce48d2b0dec68747f6c",
  "exp": 1670000000,
  "iat": 1670000000,
  "sub": "68028ce48d2b0dec68747f6c",
  "aud": "https://production.plaid.com",
  "iss": "https://production.plaid.com",
  "token_type": "Bearer",
  "request_id": "m8MDqcS6F3lzqvP"
}
```

\=\*=\*=\*=

#### /oauth/revoke 

#### Revoke an OAuth token 

[/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) revokes an access or refresh token, preventing any further use. If a refresh token is revoked, all access and refresh tokens derived from it are also revoked, including exchanged tokens.  
Note: This endpoint supports `Content-Type: application/x-www-form-urlencoded` as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification.

#### Request fields 

**token** (required, string)  
An OAuth token of any type (refresh\_token, access\_token, etc)

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

**client\_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 as either secret or client\_secret.

**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 as either secret or client\_secret.

```javascript
const request = {
  token: accessToken
};


try {
  const response = await client.oauthRevoke(request);
} catch (error) {
    ...
}
```

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

```json
{
  "request_id": "m8MDqcS6F3lzqvP"
}
```

---


# API - Reseller partners | Plaid Docs

Partner endpoints and webhooks 
===============================

#### Create and manage end customers 

For general, non-reference documentation, see [Reseller partners](https://plaid.com/docs/account/resellers/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) | Create an end customer |
| [/partner/customer/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomerget) | Get the status of an end customer |
| [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) | Get the OAuth-institution registration status for an end customer |
| [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) | Enable an end customer in Production |
| [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) | Remove an end customer |

| Webhooks |  |
| --- | --- |
| [PARTNER\_END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED](https://plaid.com/docs/api/partner/index.html.md#partner_end_customer_oauth_status_updated) | Customer OAuth status updated |

### Endpoints 

\=\*=\*=\*=

#### /partner/customer/create 

#### Creates a new end customer for a Plaid reseller. 

The [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) endpoint is used by reseller partners to create end customers. To create end customers, it should be called in the Production environment only, even when creating Sandbox API keys. If called in the Sandbox environment, it will return a sample response, but no customer will be created and the API keys will not be valid.

#### Request fields and example 

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

**company\_name** (required, string)  
The company name of the end customer being created. This will be used to display the end customer in the Plaid Dashboard. It will not be shown to end users.

**is\_diligence\_attested** (required, boolean)  
Denotes whether or not the partner has completed attestation of diligence for the end customer to be created.

**products** (\[string\])  
The products to be enabled for the end customer. If empty or null, this field will default to the products enabled for the reseller at the time this endpoint is called. Possible values: assets, auth, balance, identity, income\_verification, investments, liabilities, transactions, employment, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights

**create\_link\_customization** (boolean)  
If true, the end customer's default Link customization will be set to match the partner's. You can always change the end customer's Link customization in the Plaid Dashboard. See the Link Customization docs for more information.

**logo** (string)  
Base64-encoded representation of the end customer's logo. Must be a PNG of size 1024x1024 under 4MB. The logo will be shared with financial institutions and shown to the end user during Link flows. A logo is required if create\_link\_customization is true. If create\_link\_customization is false and the logo is omitted, the partner's logo will be used if one exists, otherwise a stock logo will be used.

**legal\_entity\_name** (required, string)  
The end customer's legal name. This will be shared with financial institutions as part of the OAuth registration process. It will not be shown to end users.

**website** (required, string)  
The end customer's website.

**application\_name** (required, string)  
The name of the end customer's application. This will be shown to end users when they go through the Plaid Link flow. The application name must be unique and cannot match the name of another application already registered with Plaid.

**technical\_contact** (object)  
The technical contact for the end customer. Defaults to partner's technical contact if omitted.

string

string

string

**billing\_contact** (object)  
The billing contact for the end customer. Defaults to partner's billing contact if omitted.

string

string

string

**customer\_support\_info** (object)  
This information is public. Users of your app will see this information when managing connections between your app and their bank accounts in Plaid Portal. Defaults to partner's customer support info if omitted. This field is mandatory for partners whose Plaid accounts were created after November 26, 2024 and will be mandatory for all partners by the 1033 compliance deadline.

**customer\_support\_info->email** (string)  
This field is mandatory for partners whose Plaid accounts were created after November 26, 2024 and will be mandatory for all partners by the 1033 compliance deadline.

string

string

string

**address** (required, object)  
The end customer's address.

string

string

string

string

**address->country\_code** (string)  
ISO-3166-1 alpha-2 country code standard.

**is\_bank\_addendum\_completed** (required, boolean)  
Denotes whether the partner has forwarded the Plaid bank addendum to the end customer.

**assets\_under\_management** (object)  
Assets under management for the given end customer. Required for end customers with monthly service commitments.

required, number

required, string

**redirect\_uris** (\[string\])  
A list of URIs indicating the destination(s) where a user can be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or another app. URIs should not contain any query parameters. When used in Production, URIs must use https. To specify any subdomain, use \* as a wildcard character, e.g. https://\*.example.com/oauth.html. To modify redirect URIs for an end customer after creating them, go to the end customer's API page in the Dashboard.

**registration\_number** (string)  
The unique identifier assigned to a financial institution by regulatory authorities, if applicable. For banks, this is the FDIC Certificate Number. For credit unions, this is the Credit Union Charter Number.

```javascript
const request: PartnerCustomerCreateRequest = {
  address: {
    city: city,
    country_code: countryCode,
    postal_code: postalCode,
    region: region,
    street: street,
  },
  application_name: applicationName,
  billing_contact: {
    email: billingEmail,
    given_name: billingGivenName,
    family_name: billingFamilyName,
  },
  customer_support_info: {
    email: supportEmail,
    phone_number: supportPhoneNumber,
    contact_url: supportContactUrl,
    link_update_url: linkUpdateUrl,
  },
  company_name: companyName,
  is_bank_addendum_completed: true,
  is_diligence_attested: true,
  legal_entity_name: legalEntityName,
  products: products,
  technical_contact: {
    email: technicalEmail,
    given_name: technicalGivenName,
    family_name: technicalFamilyName,
  },
  website: website,
};
try {
  const response = await plaidClient.partnerCustomerCreate(request);
  const endCustomer = response.data.end_customer;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**end\_customer** (object)  
The details for the newly created end customer, including secrets for Sandbox and Limited Production.

**end\_customer->client\_id** (string)  
The client\_id of the end customer.

**end\_customer->company\_name** (string)  
The company name associated with the end customer.

**end\_customer->status** (string)  
The status of the given end customer. UNDER\_REVIEW: The end customer has been created and enabled in Sandbox and Limited Production. The end customer must be manually reviewed by the Plaid team before it can be enabled in full production, at which point its status will automatically transition to PENDING\_ENABLEMENT or DENIED. PENDING\_ENABLEMENT: The end customer is ready to be fully enabled in the Production environment. Call the /partner/customer/enable endpoint to enable the end customer in full Production. ACTIVE: The end customer has been fully enabled in all environments. DENIED: The end customer has been created and enabled in Sandbox and Limited Production, but it did not pass review by the Plaid team and therefore cannot be enabled for full Production access. Talk to your Account Manager for more information. Possible values: UNDER\_REVIEW, PENDING\_ENABLEMENT, ACTIVE, DENIED

**end\_customer->secrets** (object)  
The secrets for the newly created end customer.

**end\_customer->secrets->sandbox** (string)  
The end customer's secret key for the Sandbox environment.

**end\_customer->secrets->production** (string)  
The end customer's secret key for the Production environment. The end customer will be provided with a limited number of credits to test in the Production environment before full enablement.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "end_customer": {
    "client_id": "7f57eb3d2a9j6480121fx361",
    "company_name": "Plaid",
    "status": "ACTIVE",
    "secrets": {
      "sandbox": "b60b5201d006ca5a7081d27c824d77",
      "production": "79g03eoofwl8240v776r2h667442119"
    }
  },
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /partner/customer/get 

#### Returns a Plaid reseller's end customer. 

The [/partner/customer/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomerget) endpoint is used by reseller partners to retrieve data about a single end customer.

#### Request fields and example 

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

required, string

```javascript
const request: PartnerCustomerGetRequest = {
  end_customer_client_id: clientId,
};
try {
  const response = await plaidClient.partnerCustomerGet(request);
  const endCustomer = response.data.end_customer;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**end\_customer** (object)  
The details for an end customer.

**end\_customer->client\_id** (string)  
The client\_id of the end customer.

**end\_customer->company\_name** (string)  
The company name associated with the end customer.

**end\_customer->status** (string)  
The status of the given end customer. UNDER\_REVIEW: The end customer has been created and enabled in Sandbox and Limited Production. The end customer must be manually reviewed by the Plaid team before it can be enabled in full production, at which point its status will automatically transition to PENDING\_ENABLEMENT or DENIED. PENDING\_ENABLEMENT: The end customer is ready to be fully enabled in the Production environment. Call the /partner/customer/enable endpoint to enable the end customer in full Production. ACTIVE: The end customer has been fully enabled in all environments. DENIED: The end customer has been created and enabled in Sandbox and Limited Production, but it did not pass review by the Plaid team and therefore cannot be enabled for full Production access. Talk to your Account Manager for more information. Possible values: UNDER\_REVIEW, PENDING\_ENABLEMENT, ACTIVE, DENIED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "end_customer": {
    "client_id": "7f57eb3d2a9j6480121fx361",
    "company_name": "Plaid",
    "status": "ACTIVE"
  },
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /partner/customer/oauth\_institutions/get 

#### Returns OAuth-institution registration information for a given end customer. 

The [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) endpoint is used by reseller partners to retrieve OAuth-institution registration information about a single end customer. To learn how to set up a webhook to listen to status update events, visit the [reseller documentation](https://plaid.com/docs/account/resellers/index.html.md#enabling-end-customers) .

#### Request fields and example 

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

required, string

```javascript
const request: PartnerCustomerOAuthInstitutionsGetRequest = {
  end_customer_client_id: clientId,
};
try {
  const response = await plaidClient.partnerCustomerOAuthInstitutionsGet(
    request,
  );
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**flowdown\_status** (string)  
The status of the addendum to the Plaid MSA ("flowdown") for the end customer. Possible values: NOT\_STARTED, IN\_REVIEW, NEGOTIATION, COMPLETE

**questionnaire\_status** (string)  
The status of the end customer's security questionnaire. Possible values: NOT\_STARTED, RECEIVED, COMPLETE

**institutions** (\[object\])  
The OAuth institutions with which the end customer's application is being registered.

string

string

**institutions->environments** (object)  
Registration statuses by environment.

**institutions->environments->development** (string)  
The registration status for the end customer's application. Possible values: NOT\_STARTED, PROCESSING, APPROVED, ENABLED, ATTENTION\_REQUIRED

**institutions->environments->production** (string)  
The registration status for the end customer's application. Possible values: NOT\_STARTED, PROCESSING, APPROVED, ENABLED, ATTENTION\_REQUIRED

**institutions->production\_enablement\_date** (nullable, string)  
The date on which the end customer's application was approved by the institution, or an empty string if their application has not yet been approved.

**institutions->classic\_disablement\_date** (nullable, string)  
The date on which non-OAuth Item adds will no longer be supported for this institution, or an empty string if no such date has been set by the institution.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "flowdown_status": "COMPLETE",
  "questionnaire_status": "COMPLETE",
  "institutions": [
    {
      "name": "Chase",
      "institution_id": "ins_56",
      "environments": {
        "production": "PROCESSING"
      },
      "production_enablement_date": null,
      "classic_disablement_date": "2022-06-30"
    },
    {
      "name": "Capital One",
      "institution_id": "ins_128026",
      "environments": {
        "production": "ENABLED"
      },
      "production_enablement_date": "2022-12-19",
      "classic_disablement_date": null
    }
  ],
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /partner/customer/enable 

#### Enables a Plaid reseller's end customer in the Production environment. 

The [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) endpoint is used by reseller partners to enable an end customer in the full Production environment.

#### Request fields and example 

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

required, string

```javascript
const request: PartnerCustomerEnableRequest = {
  end_customer_client_id: clientId,
};
try {
  const response = await plaidClient.partnerCustomerEnable(request);
  const productionSecret = response.data.production_secret;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**production\_secret** (string)  
The end customer's secret key for the Production environment.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "production_secret": "79g03eoofwl8240v776r2h667442119",
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /partner/customer/remove 

#### Removes a Plaid reseller's end customer. 

The [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) endpoint is used by reseller partners to remove an end customer. Removing an end customer will remove it from view in the Plaid Dashboard and deactivate its API keys. This endpoint can only be used to remove an end customer that has not yet been enabled in full Production.

#### Request fields and example 

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

**end\_customer\_client\_id** (required, string)  
The client\_id of the end customer to be removed.

```javascript
const request: PartnerCustomerRemoveRequest = {
  end_customer_client_id: clientId,
};
try {
  const response = await plaidClient.partnerCustomerRemove(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "4zlKapIkTm8p5KM"
}
```

### Webhooks 

\=\*=\*=\*=

#### PARTNER\_END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED 

The webhook of type `PARTNER` and code `END_CUSTOMER_OAUTH_STATUS_UPDATED` will be fired when a partner's end customer has an update on their OAuth registration status with an institution.

#### Properties 

**webhook\_type** (string)  
PARTNER

**webhook\_code** (string)  
END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED

**end\_customer\_client\_id** (string)  
The client ID of the end customer

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

**institution\_id** (string)  
The institution ID

**institution\_name** (string)  
The institution name

**status** (string)  
The OAuth status of the update Possible values: not-started, processing, approved, enabled, attention-required

```json
{
  "webhook_type": "PARTNER",
  "webhook_code": "END_CUSTOMER_OAUTH_STATUS_UPDATED",
  "end_customer_client_id": "634758733ebb4f00134b85ea",
  "environment": "production",
  "institution_id": "ins_127989",
  "institution_name": "Bank of America",
  "status": "attention-required"
}
```

---


# API - Postman Collection | Plaid Docs

Plaid Postman Collection 
=========================

#### Learn more about the Plaid Postman Collection, which allows you to send API requests without code 

#### Introduction 

Interested in experimenting with the Plaid API without having to write a full-stack application? Plaid offers a [Postman Collection](https://github.com/plaid/plaid-postman) as a convenient tool for exploring Plaid API endpoints without writing code. The Postman Collection provides pre-formatted requests for almost all of Plaid's API endpoints that you can call from their desktop application, or a web browser. All you have to do is fill in your API keys and any arguments.

To get started using the Postman collection, you will need a Plaid account with access to the Sandbox environment, an account at [Postman.com](https://www.postman.com) , and (optionally) the Postman [desktop application](https://www.postman.com/downloads/) . Once you have all the prerequisites, visit our [GitHub page](https://github.com/plaid/plaid-postman) and click the "Run in Postman" button to load up the Plaid collection of endpoints.

(An image of "Postman interface showing Plaid API call setup for 'Retrieve Auth' with JSON body and response displaying account details.")

---


# API - Processor partners | Plaid Docs

Processor partner endpoints 
============================

#### API reference for endpoints for use by Plaid partners 

Partner processor endpoints are used by Plaid partners to integrate with Plaid. Instead of using an `access_token` associated with a Plaid `Item`, these endpoints use a `processor_token` to identify a single financial account. These endpoints are used only by partners and not by developers who are using those partners' APIs. If you are a Plaid developer who would like to use a partner, see [Processor token endpoints](https://plaid.com/docs/api/processors/index.html.md) . To learn how to move money with one of our partners, see [Move money with Auth](https://plaid.com/docs/auth/partnerships/index.html.md) .

| In this section |  |
| --- | --- |
| [/processor/account/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoraccountget) | Fetch Account data |
| [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) | Fetch Auth data |
| [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) | Fetch Balance data |
| [/processor/identity/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentityget) | Fetch Identity data |
| [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) | Retrieve Identity match scores |
| [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) | Fetch Investments Holdings data |
| [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) | Fetch Investments Transactions data |
| [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) | Retrieve Liabilities data |
| [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) | Retrieve Signal scores |
| [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) | Report whether you initiated an ACH transaction |
| [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) | Report a return for an ACH transaction |
| [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) | Prepare a processor token for Signal |
| [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) | Set the webhook URL for a processor token |
| [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) | Get transaction data or incremental transaction updates |
| [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) | Fetch transaction data |
| [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) | Fetch recurring transaction data |
| [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) | Refresh transaction data |

| Webhooks |  |
| --- | --- |
| [WEBHOOK\_UPDATE\_ACKNOWLEDGED](https://plaid.com/docs/api/processor-partners/index.html.md#webhook_update_acknowledged) | Item's webhook receiver endpoint has been updated |

\=\*=\*=\*=

#### /processor/account/get 

#### Retrieve the account associated with a processor token 

This endpoint returns the account associated with a given processor token.  
This endpoint retrieves cached information, rather than extracting fresh information from the institution. As a result, the account balance returned may not be up-to-date; for realtime balance information, use [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) instead. Note that some information is nullable.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

```javascript
try {
  const request: ProcessorAccountGetRequest = {
    processor_token: processorToken,
  };
  const response = await plaidClient.ProcessorAccountGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**institution\_id** (string)  
The Plaid Institution ID associated with the Account.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv",
    "balances": {
      "available": 100,
      "current": 110,
      "limit": null,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Checking",
    "subtype": "checking",
    "type": "depository"
  },
  "institution_id": "ins_109508",
  "request_id": "1zlMf"
}
```

\=\*=\*=\*=

#### /processor/auth/get 

#### Retrieve Auth data 

The [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) endpoint returns the bank account and bank identification number (such as the routing number, for US accounts), for a checking, savings, or cash management account that''s associated with a given `processor_token`. The endpoint also returns high-level account data and balances when available.  
Versioning note: API versions 2019-05-29 and earlier use a different schema for the `numbers` object returned by this endpoint. For details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2020-09-14) .

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

```javascript
const request: ProcessorAuthGetRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorAuthGet(request);
```

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

**numbers** (object)  
An object containing identifying numbers used for making electronic transfers to and from the account. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by the account for which auth data has been requested, a null value will be returned.

**numbers->ach** (nullable, object)  
Identifying information for transferring money to or from a US account via ACH or wire transfer.

**numbers->ach->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->ach->account** (string)  
The ACH account number for the account. At certain institutions, including Chase, PNC, and (coming May 2025) US Bank, you will receive "tokenized" routing and account numbers, which are not the user's actual account and routing numbers. For important details on how this may impact your integration and on how to avoid fraud, user confusion, and ACH returns, see Tokenized account numbers.

**numbers->ach->is\_tokenized\_account\_number** (boolean)  
Indicates whether the account number is tokenized by the institution. For important details on how tokenized account numbers may impact your integration, see Tokenized account numbers.

**numbers->ach->routing** (string)  
The ACH routing number for the account. This may be a tokenized routing number. For more information, see Tokenized account numbers.

**numbers->ach->wire\_routing** (nullable, string)  
The wire transfer routing number for the account. This field is only populated if the institution is known to use a separate wire transfer routing number. Many institutions do not have a separate wire routing number and use the ACH routing number for wires instead. It is recommended to have the end user manually confirm their wire routing number before sending any wires to their account, especially if this field is null.

**numbers->eft** (nullable, object)  
Identifying information for transferring money to or from a Canadian bank account via EFT.

**numbers->eft->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->eft->account** (string)  
The EFT account number for the account

**numbers->eft->institution** (string)  
The EFT institution number for the account

**numbers->eft->branch** (string)  
The EFT branch number for the account

**numbers->international** (nullable, object)  
Identifying information for transferring money to or from an international bank account via wire transfer.

**numbers->international->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->international->iban** (string)  
The International Bank Account Number (IBAN) for the account

**numbers->international->bic** (string)  
The Bank Identifier Code (BIC) for the account

**numbers->bacs** (nullable, object)  
Identifying information for transferring money to or from a UK bank account via BACS.

**numbers->bacs->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->bacs->account** (string)  
The BACS account number for the account

**numbers->bacs->sort\_code** (string)  
The BACS sort code for the account

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

```json
{
  "account": {
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "balances": {
      "available": 100,
      "current": 110,
      "iso_currency_code": "USD",
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Checking",
    "subtype": "checking",
    "type": "depository"
  },
  "numbers": {
    "ach": {
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
    },
    "eft": {
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "021",
      "branch": "01140"
    },
    "international": {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "bic": "NWBKGB21",
      "iban": "GB29NWBK60161331926819"
    },
    "bacs": {
      "account": "31926819",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "sort_code": "601613"
    }
  },
  "request_id": "1zlMf"
}
```

\=\*=\*=\*=

#### /processor/balance/get 

#### Retrieve Balance data 

The [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) endpoint returns the real-time balance for each of an Item's accounts. While other endpoints may return a balance object, only [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) forces the available and current balance fields to be refreshed rather than cached.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**options** (object)  
Optional parameters to /processor/balance/get.

**options->min\_last\_updated\_datetime** (string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get. This field is only necessary when the institution is ins\_128026 (Capital One), and one or more account types being requested is a non-depository account (such as a credit card) as Capital One does not provide real-time balance for non-depository accounts. In this case, a value must be provided or an INVALID\_REQUEST error with the code of INVALID\_FIELD will be returned. For all other institutions, as well as for depository accounts at Capital One (including all checking and savings accounts) this field is ignored and real-time balance information will be fetched. If this field is not ignored, and no acceptable balance is available, an INVALID\_RESULT error with the code LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE will be returned. Format: date-time

```javascript
const request: ProcessorBalanceGetRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorBalanceGet(request);
```

#### Response fields and example 

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv",
    "balances": {
      "available": 100,
      "current": 110,
      "limit": null,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Checking",
    "subtype": "checking",
    "type": "depository"
  },
  "request_id": "1zlMf"
}
```

\=\*=\*=\*=

#### /processor/identity/get 

#### Retrieve Identity data 

The [/processor/identity/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentityget) endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

```javascript
const request: ProcessorIdentityGetRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorIdentityGet(request);
```

#### Response fields and example 

**account** (object)  
Identity information about an account

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**account->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution; detecting whether the linked account is a business account is not currently supported. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning

**account->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**account->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**account->owners->phone\_numbers->data** (string)  
The phone number.

**account->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**account->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**account->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**account->owners->emails->data** (string)  
The email address.

**account->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**account->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**account->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**account->owners->addresses->data** (object)  
Data about the components comprising an address.

**account->owners->addresses->data->city** (nullable, string)  
The full city name

**account->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**account->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**account->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**account->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**account->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "XMGPJy4q1gsQoKd5z9R3tK8kJ9EWL8SdkgKMq",
    "balances": {
      "available": 100,
      "current": 110,
      "iso_currency_code": "USD",
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Standard 0% Interest Checking",
    "owners": [
      {
        "addresses": [
          {
            "data": {
              "city": "Malakoff",
              "country": "US",
              "postal_code": "14236",
              "region": "NY",
              "street": "2992 Cameron Road"
            },
            "primary": true
          },
          {
            "data": {
              "city": "San Matias",
              "country": "US",
              "postal_code": "93405-2255",
              "region": "CA",
              "street": "2493 Leisure Lane"
            },
            "primary": false
          }
        ],
        "emails": [
          {
            "data": "accountholder0@example.com",
            "primary": true,
            "type": "primary"
          },
          {
            "data": "accountholder1@example.com",
            "primary": false,
            "type": "secondary"
          },
          {
            "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
            "primary": false,
            "type": "other"
          }
        ],
        "names": [
          "Alberta Bobbeth Charleson"
        ],
        "phone_numbers": [
          {
            "data": "2025550123",
            "primary": false,
            "type": "home"
          },
          {
            "data": "1112224444",
            "primary": false,
            "type": "work"
          },
          {
            "data": "1112225555",
            "primary": false,
            "type": "mobile1"
          }
        ]
      }
    ],
    "subtype": "checking",
    "type": "depository"
  },
  "request_id": "eOPkBl6t33veI2J"
}
```

\=\*=\*=\*=

#### /processor/identity/match 

#### Retrieve identity match score 

The [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution.  
Fields within the `balances` object will always be null when retrieved by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . Instead, use the free [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint to request balance cached data, or [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) for real-time data.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**user** (object)  
The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks.

**user->legal\_name** (string)  
The user's full legal name.

**user->phone\_number** (string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
Data about the components comprising an address.

**user->address->city** (string)  
The full city name

**user->address->region** (string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**user->address->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**user->address->postal\_code** (string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**user->address->country** (string)  
The ISO 3166-1 alpha-2 country code

```javascript
const request: ProcessorIdentityMatchRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorIdentityMatch(request);
```

#### Response fields and example 

**account** (object)  
Identity match scores for an account

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**account->legal\_name** (nullable, object)  
Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled.

**account->legal\_name->score** (nullable, integer)  
Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null.

**account->legal\_name->is\_first\_name\_or\_last\_name\_match** (nullable, boolean)  
first or last name completely matched, likely a family member

**account->legal\_name->is\_nickname\_match** (nullable, boolean)  
nickname matched, example Jennifer and Jenn.

**account->legal\_name->is\_business\_name\_detected** (nullable, boolean)  
Is true if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A true result generally indicates that an account's name is a business name. However, a false result does not mean the account name is not a business name, as some businesses do not use these strings in the names used for their financial institution accounts.

**account->phone\_number** (nullable, object)  
Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.

**account->phone\_number->score** (nullable, integer)  
Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension, etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null.

**account->email\_address** (nullable, object)  
Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.

**account->email\_address->score** (nullable, integer)  
Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null.

**account->address** (nullable, object)  
Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.

**account->address->score** (nullable, integer)  
Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-70 is a partial match, anything below 70 is considered a weak match. Typically, the match threshold should be set to a score of 70 or higher. If the address is missing from either the API or financial institution, this is null.

**account->address->is\_postal\_code\_match** (nullable, boolean)  
postal code was provided for both and was a match

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
    "balances": {
      "available": null,
      "current": null,
      "iso_currency_code": null,
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Standard 0% Interest Checking",
    "legal_name": {
      "score": 90,
      "is_nickname_match": true,
      "is_first_name_or_last_name_match": true,
      "is_business_name_detected": false
    },
    "phone_number": {
      "score": 100
    },
    "email_address": {
      "score": 100
    },
    "address": {
      "score": 100,
      "is_postal_code_match": true
    },
    "subtype": "checking",
    "type": "depository"
  },
  "request_id": "3nARps6TOYtbACO"
}
```

\=\*=\*=\*=

#### /processor/investments/holdings/get 

#### Retrieve Investment Holdings 

This endpoint returns the stock position data of the account associated with a given processor token.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

```javascript
const request: ProcessorInvestmentsHoldingsGetRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorInvestmentsHoldingsGet(request);
```

#### Response fields and example 

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**holdings** (\[object\])  
The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the securities field.

**holdings->account\_id** (string)  
The Plaid account\_id associated with the holding.

**holdings->security\_id** (string)  
The Plaid security\_id associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The security\_id for the same security will typically be the same across different institutions, but this is not guaranteed. The security\_id does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**holdings->institution\_price** (number)  
The last price given by the institution for this security. Format: double

**holdings->institution\_price\_as\_of** (nullable, string)  
The date at which institution\_price was current. Format: date

**holdings->institution\_price\_datetime** (nullable, string)  
Date and time at which institution\_price was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). Format: date-time

**holdings->institution\_value** (number)  
The value of the holding, as reported by the institution. Format: double

**holdings->cost\_basis** (nullable, number)  
The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding). Format: double

**holdings->quantity** (number)  
The total quantity of the asset held, as reported by the financial institution. If the security is an option, quantity will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: double

**holdings->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the holding. Always null if unofficial\_currency\_code is non-null.

**holdings->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**holdings->vested\_quantity** (nullable, number)  
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities. Format: double

**holdings->vested\_value** (nullable, number)  
The value of the vested holdings as reported by the institution. Format: double

**securities** (\[object\])  
Objects describing the securities held in the account.

**securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**securities->isin** (nullable, string)  
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->cusip** (nullable, string)  
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->sedol** (deprecated, nullable, string)  
(Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK.

**securities->institution\_security\_id** (nullable, string)  
An identifier given to the security by the institution

**securities->institution\_id** (nullable, string)  
If institution\_security\_id is present, this field indicates the Plaid institution\_id of the institution to whom the identifier belongs.

**securities->proxy\_security\_id** (nullable, string)  
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.

**securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**securities->is\_cash\_equivalent** (nullable, boolean)  
Indicates that a security is a highly liquid asset and can be treated like cash.

**securities->type** (nullable, string)  
The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**securities->subtype** (nullable, string)  
The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: Possible values: asset backed security, bill, bond, bond with warrants, cash, cash management bill, common stock, convertible bond, convertible equity, cryptocurrency, depositary receipt, depositary receipt on debt, etf, float rating note, fund of funds, hedge fund, limited partnership unit, medium term note, money market debt, mortgage backed security, municipal bond, mutual fund, note, option, other, preferred convertible, preferred equity, private equity fund, real estate investment trust, structured equity product, treasury inflation protected securities, unit, warrant.

**securities->close\_price** (nullable, number)  
Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update\_datetime with the time when the price was last updated. Format: double

**securities->close\_price\_as\_of** (nullable, string)  
Date for which close\_price is accurate. Always null if close\_price is null. Format: date

**securities->update\_datetime** (nullable, string)  
Date and time at which close\_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close\_price is null. Format: date-time

**securities->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the price given. Always null if unofficial\_currency\_code is non-null.

**securities->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the security. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**securities->market\_identifier\_code** (nullable, string)  
The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded.

**securities->sector** (nullable, string)  
The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->industry** (nullable, string)  
The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->option\_contract** (nullable, object)  
Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a custom Sandbox user and the ticker field of the custom security follows the OCC Option Symbol standard with no spaces. For an example of simulating this in Sandbox, see the custom Sandbox GitHub.

**securities->option\_contract->contract\_type** (string)  
The type of this option contract. It is one of: put: for Put option contracts call: for Call option contracts

**securities->option\_contract->expiration\_date** (string)  
The expiration date for this option contract, in ISO 8601 format. Format: date

**securities->option\_contract->strike\_price** (number)  
The strike price for this option contract, per share of security. Format: double

**securities->option\_contract->underlying\_security\_ticker** (string)  
The ticker of the underlying security for this option contract.

**securities->fixed\_income** (nullable, object)  
Details about the fixed income security.

**securities->fixed\_income->yield\_rate** (nullable, object)  
Details about a fixed income security's expected rate of return.

**securities->fixed\_income->yield\_rate->percentage** (number)  
The fixed income security's expected rate of return. Format: double

**securities->fixed\_income->yield\_rate->type** (nullable, string)  
The type of rate which indicates how the predicted yield was calculated. It is one of: coupon: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. coupon\_equivalent: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. discount: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. yield: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: coupon, coupon\_equivalent, discount, yield, null

**securities->fixed\_income->maturity\_date** (nullable, string)  
The maturity date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->issue\_date** (nullable, string)  
The issue date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->face\_value** (nullable, number)  
The face value that is paid upon maturity of the fixed income security, per unit of security. Format: double

**is\_investments\_fallback\_item** (boolean)  
When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
    "balances": {
      "available": null,
      "current": 110.01,
      "iso_currency_code": "USD",
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "5555",
    "name": "Plaid IRA",
    "official_name": null,
    "subtype": "ira",
    "type": "investment"
  },
  "holdings": [
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 0.01,
      "iso_currency_code": "USD",
      "quantity": 0.01,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null
    },
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 0.01,
      "institution_price": 0.011,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 110,
      "iso_currency_code": "USD",
      "quantity": 10000,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "unofficial_currency_code": null
    }
  ],
  "securities": [
    {
      "close_price": 0.011,
      "close_price_as_of": "2021-04-13",
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "Nflx Feb 01'18 $355 Call",
      "proxy_security_id": null,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "sedol": null,
      "ticker_symbol": "NFLX180201C00355000",
      "type": "derivative",
      "subtype": "option",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Technology Services",
      "industry": "Internet Software or Services",
      "option_contract": {
        "contract_type": "call",
        "expiration_date": "2018-02-01",
        "strike_price": 355,
        "underlying_security_ticker": "NFLX"
      },
      "fixed_income": null
    },
    {
      "close_price": 1,
      "close_price_as_of": null,
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": true,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "U S Dollar",
      "proxy_security_id": null,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "sedol": null,
      "ticker_symbol": "USD",
      "type": "cash",
      "subtype": "cash",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": null,
      "sector": null,
      "industry": null,
      "option_contract": null,
      "fixed_income": null
    }
  ],
  "request_id": "24MxmGFZz89Xg2f",
  "is_investments_fallback_item": false
}
```

\=\*=\*=\*=

#### /processor/investments/transactions/get 

#### Get investment transactions data 

The [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) endpoint allows developers to retrieve up to 24 months of user-authorized transaction data for the investment account associated with the processor token.  
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift.  
Due to the potentially large number of investment transactions associated with the account, results are paginated. Manipulate the count and offset parameters in conjunction with the `total_investment_transactions` response body field to fetch all available investment transactions.  
Note that Investments does not have a webhook to indicate when initial transaction data has loaded (unless you use the `async_update` option). Instead, if transactions data is not ready when [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) is first called, Plaid will wait for the data. For this reason, calling [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) immediately after Link may take up to one to two minutes to return.  
Data returned by the asynchronous investments extraction flow (when `async_update` is set to true) may not be immediately available to [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) . To be alerted when the data is ready to be fetched, listen for the `HISTORICAL_UPDATE` webhook. If no investments history is ready when [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) is called, it will return a `PRODUCT_NOT_READY` error.  
To receive Investments Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint.

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

**options** (object)  
An optional object to filter /investments/transactions/get results. If provided, must be non-null.

**options->account\_ids** (\[string\])  
An array of account\_ids to retrieve for the Item.

**options->count** (integer)  
The number of transactions to fetch. Default: 100 Minimum: 1 Maximum: 500

**options->offset** (integer)  
The number of transactions to skip when fetching transaction history Default: 0 Minimum: 0

**options->async\_update** (boolean)  
If the Item was not initialized with the investments product via the products, required\_if\_supported\_products, or optional\_products array when calling /link/token/create, and async\_update is set to true, the initial Investments extraction will happen asynchronously. Plaid will subsequently fire a HISTORICAL\_UPDATE webhook when the extraction completes. When false, Plaid will wait to return a response until extraction completion and no HISTORICAL\_UPDATE webhook will fire. Note that while the extraction is happening asynchronously, calls to /investments/transactions/get and /investments/refresh will return PRODUCT\_NOT\_READY errors until the extraction completes. Default: false

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

**start\_date** (required, string)  
The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date

**end\_date** (required, string)  
The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date

```javascript
const request: ProcessorInvestmentsTransactionsGetRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorInvestmentsTransactionsGet(request);
```

#### Response fields and example 

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**investment\_transactions** (\[object\])  
An array containing investment transactions from the account. Investments transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter.

**investment\_transactions->investment\_transaction\_id** (string)  
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment\_transaction\_id is case sensitive.

**investment\_transactions->account\_id** (string)  
The account\_id of the account against which this transaction posted.

**investment\_transactions->security\_id** (nullable, string)  
The security\_id to which this transaction is related.

**investment\_transactions->date** (string)  
The ISO 8601 posting date for the transaction. Format: date

**investment\_transactions->name** (string)  
The institution’s description of the transaction.

**investment\_transactions->quantity** (number)  
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: double

**investment\_transactions->amount** (number)  
The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: double

**investment\_transactions->price** (number)  
The price of the security at which this transaction occurred. Format: double

**investment\_transactions->fees** (nullable, number)  
The combined value of all fees applied to this transaction Format: double

**investment\_transactions->type** (string)  
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: buy, sell, cancel, cash, fee, transfer

**investment\_transactions->subtype** (string)  
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal

**investment\_transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**investment\_transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**securities** (\[object\])  
All securities for which there is a corresponding transaction being fetched.

**securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**securities->isin** (nullable, string)  
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->cusip** (nullable, string)  
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->sedol** (deprecated, nullable, string)  
(Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK.

**securities->institution\_security\_id** (nullable, string)  
An identifier given to the security by the institution

**securities->institution\_id** (nullable, string)  
If institution\_security\_id is present, this field indicates the Plaid institution\_id of the institution to whom the identifier belongs.

**securities->proxy\_security\_id** (nullable, string)  
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.

**securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**securities->is\_cash\_equivalent** (nullable, boolean)  
Indicates that a security is a highly liquid asset and can be treated like cash.

**securities->type** (nullable, string)  
The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**securities->subtype** (nullable, string)  
The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: Possible values: asset backed security, bill, bond, bond with warrants, cash, cash management bill, common stock, convertible bond, convertible equity, cryptocurrency, depositary receipt, depositary receipt on debt, etf, float rating note, fund of funds, hedge fund, limited partnership unit, medium term note, money market debt, mortgage backed security, municipal bond, mutual fund, note, option, other, preferred convertible, preferred equity, private equity fund, real estate investment trust, structured equity product, treasury inflation protected securities, unit, warrant.

**securities->close\_price** (nullable, number)  
Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update\_datetime with the time when the price was last updated. Format: double

**securities->close\_price\_as\_of** (nullable, string)  
Date for which close\_price is accurate. Always null if close\_price is null. Format: date

**securities->update\_datetime** (nullable, string)  
Date and time at which close\_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close\_price is null. Format: date-time

**securities->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the price given. Always null if unofficial\_currency\_code is non-null.

**securities->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the security. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**securities->market\_identifier\_code** (nullable, string)  
The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded.

**securities->sector** (nullable, string)  
The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->industry** (nullable, string)  
The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->option\_contract** (nullable, object)  
Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a custom Sandbox user and the ticker field of the custom security follows the OCC Option Symbol standard with no spaces. For an example of simulating this in Sandbox, see the custom Sandbox GitHub.

**securities->option\_contract->contract\_type** (string)  
The type of this option contract. It is one of: put: for Put option contracts call: for Call option contracts

**securities->option\_contract->expiration\_date** (string)  
The expiration date for this option contract, in ISO 8601 format. Format: date

**securities->option\_contract->strike\_price** (number)  
The strike price for this option contract, per share of security. Format: double

**securities->option\_contract->underlying\_security\_ticker** (string)  
The ticker of the underlying security for this option contract.

**securities->fixed\_income** (nullable, object)  
Details about the fixed income security.

**securities->fixed\_income->yield\_rate** (nullable, object)  
Details about a fixed income security's expected rate of return.

**securities->fixed\_income->yield\_rate->percentage** (number)  
The fixed income security's expected rate of return. Format: double

**securities->fixed\_income->yield\_rate->type** (nullable, string)  
The type of rate which indicates how the predicted yield was calculated. It is one of: coupon: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. coupon\_equivalent: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. discount: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. yield: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: coupon, coupon\_equivalent, discount, yield, null

**securities->fixed\_income->maturity\_date** (nullable, string)  
The maturity date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->issue\_date** (nullable, string)  
The issue date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->face\_value** (nullable, number)  
The face value that is paid upon maturity of the fixed income security, per unit of security. Format: double

**total\_investment\_transactions** (integer)  
The total number of transactions available within the date range specified. If total\_investment\_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**is\_investments\_fallback\_item** (boolean)  
When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow.

```json
{
  "account": {
    "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
    "balances": {
      "available": null,
      "current": 23631.9805,
      "iso_currency_code": "USD",
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "6666",
    "name": "Plaid 401k",
    "official_name": null,
    "subtype": "401k",
    "type": "investment"
  },
  "investment_transactions": [
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -8.72,
      "cancel_transaction_id": null,
      "date": "2020-05-29",
      "fees": 0,
      "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
      "iso_currency_code": "USD",
      "name": "INCOME DIV DIVIDEND RECEIVED",
      "price": 0,
      "quantity": 0,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "subtype": "dividend",
      "type": "cash",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -1289.01,
      "cancel_transaction_id": null,
      "date": "2020-05-28",
      "fees": 7.99,
      "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
      "iso_currency_code": "USD",
      "name": "SELL Matthews Pacific Tiger Fund Insti Class",
      "price": 27.53,
      "quantity": -47.74104242992852,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "subtype": "sell",
      "type": "sell",
      "unofficial_currency_code": null
    }
  ],
  "request_id": "iv4q3ZlytOOthkv",
  "securities": [
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "subtype": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Miscellaneous",
      "industry": "Investment Trusts or Mutual Funds",
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 34.73,
      "close_price_as_of": null,
      "cusip": "84470P109",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US84470P1093",
      "iso_currency_code": "USD",
      "name": "Southside Bancshares Inc.",
      "proxy_security_id": null,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "sedol": null,
      "ticker_symbol": "SBSI",
      "type": "equity",
      "subtype": "common stock",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Finance",
      "industry": "Regional Banks",
      "option_contract": null,
      "fixed_income": null
    }
  ],
  "total_investment_transactions": 2
}
```

\=\*=\*=\*=

#### /processor/signal/evaluate 

#### Evaluate a planned ACH transaction 

Use [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) to evaluate a planned ACH transaction as a processor to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.  
In order to obtain a valid score for an ACH transaction, Plaid must have an access token for the account, and the Item must be healthy (receiving product updates) or have recently been in a healthy state. If the transaction does not meet eligibility requirements, an error will be returned corresponding to the underlying cause. If [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) is called on the same transaction multiple times within a 24-hour period, cached results may be returned. For more information please refer to our error documentation on [item errors](https://plaid.com/docs/errors/item/index.html.md) and [Link in Update Mode](https://plaid.com/docs/link/update-mode/index.html.md) .  
Note: This request may take some time to complete if Signal is being added to an existing Item. This is because Plaid must communicate directly with the institution when retrieving the data for the first time. To reduce this latency, you can call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) on the Item before you need to request Signal data.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**client\_transaction\_id** (required, string)  
The unique ID that you would like to use to refer to this transaction. For your convenience mapping your internal data, you could use your internal ID/identifier for this transaction. The max length for this field is 36 characters. Min length: 1 Max length: 36

**amount** (required, number)  
The transaction amount, in USD (e.g. 102.05) Format: double

**user\_present** (boolean)  
true if the end user is present while initiating the ACH transfer and the endpoint is being called; false otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing).

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**is\_recurring** (boolean)  
true if the ACH transaction is a recurring transaction; false otherwise

**default\_payment\_method** (string)  
The default ACH or non-ACH payment method to complete the transaction. SAME\_DAY\_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day STANDARD\_ACH: standard ACH by NACHA MULTIPLE\_PAYMENT\_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME\_DAY\_ACH, STANDARD\_ACH, MULTIPLE\_PAYMENT\_METHODS

**user** (object)  
Details about the end user initiating the transaction (i.e., the account holder). When calling /signal/evaluate or /signal/processor/evaluate, this field is optional, but strongly recommended to increase the accuracy of Signal results.

**user->name** (object)  
The user's legal name

**user->name->prefix** (string)  
The user's name prefix (e.g. "Mr.")

**user->name->given\_name** (string)  
The user's given name. If the user has a one-word name, it should be provided in this field.

**user->name->middle\_name** (string)  
The user's middle name

**user->name->family\_name** (string)  
The user's family name / surname

**user->name->suffix** (string)  
The user's name suffix (e.g. "II")

**user->phone\_number** (string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567"

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
Data about the components comprising an address.

**user->address->city** (string)  
The full city name

**user->address->region** (string)  
The region or state Example: "NC"

**user->address->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**user->address->postal\_code** (string)  
The postal code

**user->address->country** (string)  
The ISO 3166-1 alpha-2 country code

**device** (object)  
Details about the end user's device. When calling /signal/evaluate or /signal/processor/evaluate, this field is optional, but strongly recommended to increase the accuracy of Signal results.

**device->ip\_address** (string)  
The IP address of the device that initiated the transaction

**device->user\_agent** (string)  
The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0")

**ruleset\_key** (string)  
The key of the Ruleset to use for this transaction. You can configure a Ruleset using the Signal dashboard located within the Plaid Dashboard. If not provided, no Ruleset will be used. This feature is currently in closed beta; to request access, contact your account manager.

```javascript
const eval_request = {
  processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  client_transaction_id: 'txn12345',
  amount: 123.45,
  client_user_id: 'user1234',
  user: {
    name: {
      prefix: 'Ms.',
      given_name: 'Jane',
      middle_name: 'Leah',
      family_name: 'Doe',
      suffix: 'Jr.',
    },
    phone_number: '+14152223333',
    email_address: 'jane.doe@example.com',
    address: {
      street: '2493 Leisure Lane',
      city: 'San Matias',
      region: 'CA',
      postal_code: '93405-2255',
      country: 'US',
    },
  },
  device: {
    ip_address: '198.30.2.2',
    user_agent:
      'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1',
  },
  user_present: true,
};


try {
  const eval_response = await plaidClient.processorSignalEvaluate(eval_request);
  const core_attributes = eval_response.data.core_attributes;
  const scores = eval_response.data.scores;
} catch (error) {
  // handle error
}
```

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

**scores** (nullable, object)  
Risk scoring details broken down by risk category.

**scores->customer\_initiated\_return\_risk** (object)  
The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.

**scores->customer\_initiated\_return\_risk->score** (integer)  
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: 1 Maximum: 99

**scores->bank\_initiated\_return\_risk** (object)  
The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.

**scores->bank\_initiated\_return\_risk->score** (integer)  
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: 1 Maximum: 99

**core\_attributes** (object)  
The core attributes object contains additional data that can be used to assess the ACH return risk. Examples of data include: days\_since\_first\_plaid\_connection: The number of days since the first time the Item was connected to an application via Plaid plaid\_connections\_count\_7d: The number of times the Item has been connected to applications via Plaid over the past 7 days plaid\_connections\_count\_30d: The number of times the Item has been connected to applications via Plaid over the past 30 days total\_plaid\_connections\_count: The number of times the Item has been connected to applications via Plaid is\_savings\_or\_money\_market\_account: Indicates whether the ACH transaction funding account is a savings/money market account For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager

**ruleset** (nullable, object)  
Details about the transaction result after evaluated by the requested Ruleset. If a ruleset\_key is not provided, this field will be omitted. This feature is currently in closed beta; to request access, contact your account manager.

**ruleset->ruleset\_key** (string)  
The key of the Ruleset used for this transaction.

**ruleset->result** (string)  
The result of the rule that was triggered for this transaction. ACCEPT: Accept the transaction for processing. REROUTE: Reroute the transaction to a different payment method, as this transaction is too risky. REVIEW: Review the transaction before proceeding. Possible values: ACCEPT, REROUTE, REVIEW

**ruleset->triggered\_rule\_details** (nullable, object)  
Rules are run in numerical order. The first rule with a logic match is triggered. These are the details of that rule.

**ruleset->triggered\_rule\_details->internal\_note** (string)  
An optional message attached to the triggered rule, defined within the Dashboard, for your internal use. Useful for debugging, such as “Account appears to be closed.”

**ruleset->triggered\_rule\_details->custom\_action\_key** (string)  
A string key, defined within the Dashboard, used to trigger programmatic behavior for a certain result. For instance, you could optionally choose to define a "3-day-hold" custom\_action\_key for an ACCEPT result.

**ruleset->outcome** (deprecated, string)  
The evaluated outcome for this transaction. This field is deprecated, use result or triggered\_rule\_details.custom\_action\_key instead.

**warnings** (\[object\])  
If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.

**warnings->warning\_type** (string)  
A broad categorization of the warning. Safe for programmatic use.

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. If you receive the ITEM\_LOGIN\_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.

**warnings->warning\_message** (string)  
A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.

```json
{
  "scores": {
    "customer_initiated_return_risk": {
      "score": 9,
      "risk_tier": 1
    },
    "bank_initiated_return_risk": {
      "score": 72,
      "risk_tier": 7
    }
  },
  "core_attributes": {
    "days_since_first_plaid_connection": 510,
    "plaid_connections_count_7d": 6,
    "plaid_connections_count_30d": 7,
    "total_plaid_connections_count": 15,
    "is_savings_or_money_market_account": false
  },
  "warnings": [],
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /processor/liabilities/get 

#### Retrieve Liabilities data 

The [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) endpoint returns various details about a loan or credit account. Liabilities data is available primarily for US financial institutions, with some limited coverage of Canadian institutions. Currently supported account types are account type `credit` with account subtype `credit card` or `paypal`, and account type `loan` with account subtype `student` or `mortgage`.  
The types of information returned by Liabilities can include balances and due dates, loan terms, and account details such as original loan amount and guarantor. Data is refreshed approximately once per day; the latest data can be retrieved by calling [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) .  
Note: This request may take some time to complete if `liabilities` was not specified as an initial product when creating the processor token. This is because Plaid must communicate directly with the institution to retrieve the additional data.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

```javascript
const request: ProcessorLiabilitiesGetRequest = {
  processor_token: processorToken,
};
const response = plaidClient.processorLiabilitiesGet(request);
```

#### Response fields and example 

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**liabilities** (object)  
An object containing liability accounts

**liabilities->credit** (nullable, \[object\])  
The credit accounts returned.

**liabilities->credit->account\_id** (nullable, string)  
The ID of the account that this liability belongs to.

**liabilities->credit->aprs** (\[object\])  
The various interest rates that apply to the account. APR information is not provided by all card issuers; if APR data is not available, this array will be empty.

**liabilities->credit->aprs->apr\_percentage** (number)  
Annual Percentage Rate applied. Format: double

**liabilities->credit->aprs->apr\_type** (string)  
The type of balance to which the APR applies. Possible values: balance\_transfer\_apr, cash\_apr, purchase\_apr, special

**liabilities->credit->aprs->balance\_subject\_to\_apr** (nullable, number)  
Amount of money that is subjected to the APR if a balance was carried beyond payment due date. How it is calculated can vary by card issuer. It is often calculated as an average daily balance. Format: double

**liabilities->credit->aprs->interest\_charge\_amount** (nullable, number)  
Amount of money charged due to interest from last statement. Format: double

**liabilities->credit->is\_overdue** (nullable, boolean)  
true if a payment is currently overdue. Availability for this field is limited.

**liabilities->credit->last\_payment\_amount** (nullable, number)  
The amount of the last payment. Format: double

**liabilities->credit->last\_payment\_date** (nullable, string)  
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Availability for this field is limited. Format: date

**liabilities->credit->last\_statement\_issue\_date** (nullable, string)  
The date of the last statement. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->credit->last\_statement\_balance** (nullable, number)  
The total amount owed as of the last statement issued Format: double

**liabilities->credit->minimum\_payment\_amount** (nullable, number)  
The minimum payment due for the next billing cycle. Format: double

**liabilities->credit->next\_payment\_due\_date** (nullable, string)  
The due date for the next payment. The due date is null if a payment is not expected. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage** (nullable, \[object\])  
The mortgage accounts returned.

**liabilities->mortgage->account\_id** (string)  
The ID of the account that this liability belongs to.

**liabilities->mortgage->account\_number** (nullable, string)  
The account number of the loan.

**liabilities->mortgage->current\_late\_fee** (nullable, number)  
The current outstanding amount charged for late payment. Format: double

**liabilities->mortgage->escrow\_balance** (nullable, number)  
Total amount held in escrow to pay taxes and insurance on behalf of the borrower. Format: double

**liabilities->mortgage->has\_pmi** (nullable, boolean)  
Indicates whether the borrower has private mortgage insurance in effect.

**liabilities->mortgage->has\_prepayment\_penalty** (nullable, boolean)  
Indicates whether the borrower will pay a penalty for early payoff of mortgage.

**liabilities->mortgage->interest\_rate** (object)  
Object containing metadata about the interest rate for the mortgage.

**liabilities->mortgage->interest\_rate->percentage** (nullable, number)  
Percentage value (interest rate of current mortgage, not APR) of interest payable on a loan. Format: double

**liabilities->mortgage->interest\_rate->type** (nullable, string)  
The type of interest charged (fixed or variable).

**liabilities->mortgage->last\_payment\_amount** (nullable, number)  
The amount of the last payment. Format: double

**liabilities->mortgage->last\_payment\_date** (nullable, string)  
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->loan\_type\_description** (nullable, string)  
Description of the type of loan, for example conventional, fixed, or variable. This field is provided directly from the loan servicer and does not have an enumerated set of possible values.

**liabilities->mortgage->loan\_term** (nullable, string)  
Full duration of mortgage as at origination (e.g. 10 year).

**liabilities->mortgage->maturity\_date** (nullable, string)  
Original date on which mortgage is due in full. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->next\_monthly\_payment** (nullable, number)  
The amount of the next payment. Format: double

**liabilities->mortgage->next\_payment\_due\_date** (nullable, string)  
The due date for the next payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->origination\_date** (nullable, string)  
The date on which the loan was initially lent. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->origination\_principal\_amount** (nullable, number)  
The original principal balance of the mortgage. Format: double

**liabilities->mortgage->past\_due\_amount** (nullable, number)  
Amount of loan (principal + interest) past due for payment. Format: double

**liabilities->mortgage->property\_address** (object)  
Object containing fields describing property address.

**liabilities->mortgage->property\_address->city** (nullable, string)  
The city name.

**liabilities->mortgage->property\_address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**liabilities->mortgage->property\_address->postal\_code** (nullable, string)  
The five or nine digit postal code.

**liabilities->mortgage->property\_address->region** (nullable, string)  
The region or state (example "NC").

**liabilities->mortgage->property\_address->street** (nullable, string)  
The full street address (example "564 Main Street, Apt 15").

**liabilities->mortgage->ytd\_interest\_paid** (nullable, number)  
The year to date (YTD) interest paid. Format: double

**liabilities->mortgage->ytd\_principal\_paid** (nullable, number)  
The YTD principal paid. Format: double

**liabilities->student** (nullable, \[object\])  
The student loan accounts returned.

**liabilities->student->account\_id** (nullable, string)  
The ID of the account that this liability belongs to. Each account can only contain one liability.

**liabilities->student->account\_number** (nullable, string)  
The account number of the loan. For some institutions, this may be a masked version of the number (e.g., the last 4 digits instead of the entire number).

**liabilities->student->disbursement\_dates** (nullable, \[string\])  
The dates on which loaned funds were disbursed or will be disbursed. These are often in the past. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->expected\_payoff\_date** (nullable, string)  
The date when the student loan is expected to be paid off. Availability for this field is limited. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->guarantor** (nullable, string)  
The guarantor of the student loan.

**liabilities->student->interest\_rate\_percentage** (number)  
The interest rate on the loan as a percentage. Format: double

**liabilities->student->is\_overdue** (nullable, boolean)  
true if a payment is currently overdue. Availability for this field is limited.

**liabilities->student->last\_payment\_amount** (nullable, number)  
The amount of the last payment. Format: double

**liabilities->student->last\_payment\_date** (nullable, string)  
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->last\_statement\_balance** (nullable, number)  
The total amount owed as of the last statement issued Format: double

**liabilities->student->last\_statement\_issue\_date** (nullable, string)  
The date of the last statement. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->loan\_name** (nullable, string)  
The type of loan, e.g., "Consolidation Loans".

**liabilities->student->loan\_status** (object)  
An object representing the status of the student loan

**liabilities->student->loan\_status->end\_date** (nullable, string)  
The date until which the loan will be in its current status. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->loan\_status->type** (nullable, string)  
The status type of the student loan Possible values: cancelled, charged off, claim, consolidated, deferment, delinquent, discharged, extension, forbearance, in grace, in military, in school, not fully disbursed, other, paid in full, refunded, repayment, transferred, pending idr

**liabilities->student->minimum\_payment\_amount** (nullable, number)  
The minimum payment due for the next billing cycle. There are some exceptions: Some institutions require a minimum payment across all loans associated with an account number. Our API presents that same minimum payment amount on each loan. The institutions that do this are: Great Lakes ( ins\_116861), Firstmark (ins\_116295), Commonbond Firstmark Services (ins\_116950), Granite State (ins\_116308), and Oklahoma Student Loan Authority (ins\_116945). Firstmark (ins\_116295 ) and Navient (ins\_116248) will display as $0 if there is an autopay program in effect. Format: double

**liabilities->student->next\_payment\_due\_date** (nullable, string)  
The due date for the next payment. The due date is null if a payment is not expected. A payment is not expected if loan\_status.type is deferment, in\_school, consolidated, paid in full, or transferred. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->origination\_date** (nullable, string)  
The date on which the loan was initially lent. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->origination\_principal\_amount** (nullable, number)  
The original principal balance of the loan. Format: double

**liabilities->student->outstanding\_interest\_amount** (nullable, number)  
The total dollar amount of the accrued interest balance. For Sallie Mae ( ins\_116944), this amount is included in the current balance of the loan, so this field will return as null. Format: double

**liabilities->student->payment\_reference\_number** (nullable, string)  
The relevant account number that should be used to reference this loan for payments. In the majority of cases, payment\_reference\_number will match account\_number, but in some institutions, such as Great Lakes (ins\_116861), it will be different.

**liabilities->student->repayment\_plan** (object)  
An object representing the repayment plan for the student loan

**liabilities->student->repayment\_plan->description** (nullable, string)  
The description of the repayment plan as provided by the servicer.

**liabilities->student->repayment\_plan->type** (nullable, string)  
The type of the repayment plan. Possible values: extended graduated, extended standard, graduated, income-contingent repayment, income-based repayment, income-sensitive repayment, interest-only, other, pay as you earn, revised pay as you earn, standard, saving on a valuable education, null

**liabilities->student->sequence\_number** (nullable, string)  
The sequence number of the student loan. Heartland ECSI (ins\_116948) does not make this field available.

**liabilities->student->servicer\_address** (object)  
The address of the student loan servicer. This is generally the remittance address to which payments should be sent.

**liabilities->student->servicer\_address->city** (nullable, string)  
The full city name

**liabilities->student->servicer\_address->region** (nullable, string)  
The region or state Example: "NC"

**liabilities->student->servicer\_address->street** (nullable, string)  
The full street address Example: "564 Main Street, APT 15"

**liabilities->student->servicer\_address->postal\_code** (nullable, string)  
The postal code

**liabilities->student->servicer\_address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**liabilities->student->ytd\_interest\_paid** (nullable, number)  
The year to date (YTD) interest paid. Availability for this field is limited. Format: double

**liabilities->student->ytd\_principal\_paid** (nullable, number)  
The year to date (YTD) principal paid. Availability for this field is limited. Format: double

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
    "balances": {
      "available": null,
      "current": 410,
      "iso_currency_code": "USD",
      "limit": 2000,
      "unofficial_currency_code": null
    },
    "mask": "3333",
    "name": "Plaid Credit Card",
    "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
    "subtype": "credit card",
    "type": "credit"
  },
  "liabilities": {
    "credit": [
      {
        "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
        "aprs": [
          {
            "apr_percentage": 15.24,
            "apr_type": "balance_transfer_apr",
            "balance_subject_to_apr": 1562.32,
            "interest_charge_amount": 130.22
          },
          {
            "apr_percentage": 27.95,
            "apr_type": "cash_apr",
            "balance_subject_to_apr": 56.22,
            "interest_charge_amount": 14.81
          },
          {
            "apr_percentage": 12.5,
            "apr_type": "purchase_apr",
            "balance_subject_to_apr": 157.01,
            "interest_charge_amount": 25.66
          },
          {
            "apr_percentage": 0,
            "apr_type": "special",
            "balance_subject_to_apr": 1000,
            "interest_charge_amount": 0
          }
        ],
        "is_overdue": false,
        "last_payment_amount": 168.25,
        "last_payment_date": "2019-05-22",
        "last_statement_issue_date": "2019-05-28",
        "last_statement_balance": 1708.77,
        "minimum_payment_amount": 20,
        "next_payment_due_date": "2020-05-28"
      }
    ],
    "mortgage": [],
    "student": []
  },
  "request_id": "dTnnm60WgKGLnKL"
}
```

\=\*=\*=\*=

#### /processor/signal/decision/report 

#### Report whether you initiated an ACH transaction 

After calling [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) , call [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) to report whether the transaction was initiated.  
If you are using the [Plaid Transfer product](https://plaid.com/docs/transfer/index.html.md) to create transfers, it is not necessary to use this endpoint, as Plaid already knows whether the transfer was initiated.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**client\_transaction\_id** (required, string)  
Must be the same as the client\_transaction\_id supplied when calling /signal/evaluate Min length: 1 Max length: 36

**initiated** (required, boolean)  
true if the ACH transaction was initiated, false otherwise. This field must be returned as a boolean. If formatted incorrectly, this will result in an INVALID\_FIELD error.

**days\_funds\_on\_hold** (integer)  
The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate. For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization. Minimum: 0

**decision\_outcome** (string)  
The payment decision from the risk assessment. APPROVE: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers. REVIEW: the transaction requires manual review REJECT: reject the transaction TAKE\_OTHER\_RISK\_MEASURES: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication NOT\_EVALUATED: if only logging the Signal results without using them Possible values: APPROVE, REVIEW, REJECT, TAKE\_OTHER\_RISK\_MEASURES, NOT\_EVALUATED

**payment\_method** (string)  
The payment method to complete the transaction after the risk assessment. It may be different from the default payment method. SAME\_DAY\_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day STANDARD\_ACH: Standard ACH by NACHA MULTIPLE\_PAYMENT\_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME\_DAY\_ACH, STANDARD\_ACH, MULTIPLE\_PAYMENT\_METHODS

**amount\_instantly\_available** (number)  
The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05). Format: double

```javascript
const decision_report_request = {
  processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  client_transaction_id: 'txn12345',
  initiated: true,
  days_funds_on_hold: 3,
};


try {
  const decision_report_response =
    await plaidClient.processorSignalDecisionReport(decision_report_request);
  const decision_request_id = decision_report_response.data.request_id;
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /processor/signal/return/report 

#### Report a return for an ACH transaction 

Call the [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) endpoint to report a returned transaction that was previously sent to the [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio.  
If you are using the [Plaid Transfer product](https://plaid.com/docs/transfer/index.html.md) to create transfers, it is not necessary to use this endpoint, as Plaid already knows whether the transfer was returned.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**client\_transaction\_id** (required, string)  
Must be the same as the client\_transaction\_id supplied when calling /processor/signal/evaluate Min length: 1 Max length: 36

**return\_code** (required, string)  
Must be a valid ACH return code (e.g. "R01") If formatted incorrectly, this will result in an INVALID\_FIELD error.

**returned\_at** (string)  
Date and time when you receive the returns from your payment processors, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Format: date-time

```javascript
const return_report_request = {
  processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  client_transaction_id: 'txn12345',
  return_code: 'R01',
};


try {
  const return_report_response = await plaidClient.processorSignalReturnReport(
    return_report_request,
  );
  const request_id = return_report_response.data.request_id;
  console.log(request_id);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /processor/signal/prepare 

#### Opt-in a processor token to Signal 

When a processor token is not initialized with Signal, call [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) to opt-in that processor token to the Signal data collection process, which will improve the accuracy of the Signal score.  
If this endpoint is called with a processor token that is already initialized with Signal, it will return a 200 response and will not modify the processor token.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

```javascript
const prepare_request = {
  processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
};


try {
  const prepare_response =
    await plaidClient.processorSignalPrepare(prepare_request);
  const prepare_request_id = prepare_response.data.request_id;
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /processor/token/webhook/update 

#### Update a processor token's webhook URL 

This endpoint allows you, the processor, to update the webhook URL associated with a processor token. This request triggers a `WEBHOOK_UPDATE_ACKNOWLEDGED` webhook to the newly specified webhook URL.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**webhook** (required, string)  
The new webhook URL to associate with the processor token. To remove a webhook from a processor token, set to null.

```javascript
try {
  const request: ProcessorTokenWebhookUpdateRequest = {
    processor_token: processorToken,
    webhook: webhook,
  };
  const response = await plaidClient.processorTokenWebhookUpdate(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "vYK11LNTfRoAMbj"
}
```

\=\*=\*=\*=

#### /processor/transactions/sync 

#### Get incremental transaction updates on a processor token 

The [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) endpoint retrieves transactions associated with an Item and can fetch updates using a cursor to track which updates have already been seen.  
For important instructions on integrating with [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) , see the [Transactions integration overview](https://plaid.com/docs/transactions/index.html.md#integration-overview) . If you are migrating from an existing integration using [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , see the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) .  
This endpoint supports `credit`, `depository`, and some `loan`\-type accounts (only those with account subtype `student`). For `investments` accounts, use [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) instead.  
When retrieving paginated updates, track both the `next_cursor` from the latest response and the original cursor from the first call in which `has_more` was `true`; if a call to [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) fails when retrieving a paginated update (e.g due to the [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) error), the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.  
If transactions data is not yet available for the Item, which can happen if the Item was not initialized with transactions during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call or if [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) was called within a few seconds of Item creation, [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) will return empty transactions arrays.  
Plaid typically checks for new transactions data between one and four times per day, depending on the institution. To find out when transactions were last updated for an Item, use the [Item Debugger](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-with-item-debugger) or call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) ; the `item.status.transactions.last_successful_update` field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) endpoint.  
To be alerted when new transactions are available, listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook.  
To receive Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

**cursor** (string)  
The cursor value represents the last update requested. Providing it will cause the response to only return changes after this update. If omitted, the entire history of updates will be returned, starting with the first-added transactions on the item. Note: The upper-bound length of this cursor is 256 characters of base64.

**count** (integer)  
The number of transaction updates to fetch. Default: 100 Minimum: 1 Maximum: 500 Exclusive min: false

**options** (object)  
An optional object to be used with the request. If specified, options must not be null.

**options->include\_original\_description** (boolean)  
Include the raw unparsed transaction description from the financial institution. Default: false

**options->days\_requested** (integer)  
This field only applies to calls for Items where the Transactions product has not already been initialized (i.e., by specifying transactions in the products, required\_if\_supported\_products, or optional\_products array when calling /link/token/create or by making a previous call to /transactions/sync or /transactions/get). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. If you are initializing your Items with transactions during the /link/token/create call (e.g. by including transactions in the /link/token/create products array), you must use the transactions.days\_requested field in the /link/token/create request instead of in the /transactions/sync request. If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via /item/remove and send the user through Link to create a new Item. Customers using Recurring Transactions should request at least 180 days of history for optimal results. Minimum: 1 Maximum: 730 Default: 90

**options->account\_id** (string)  
If provided, the returned updates and cursor will only reflect the specified account's transactions. Omitting account\_id returns updates for all accounts under the Item. Note that specifying an account\_id effectively creates a separate incremental update stream—and therefore a separate cursor—for that account. If multiple accounts are queried this way, you will maintain multiple cursors, one per account\_id. If you decide to begin filtering by account\_id after using no account\_id, start fresh with a null cursor and maintain separate (account\_id, cursor) pairs going forward. Do not reuse any previously saved cursors, as this can cause pagination errors or incomplete data. Note: An error will be returned if a provided account\_id is not associated with the Item.

```javascript
// Provide a cursor from your database if you've previously
// received one for the Item. Leave null if this is your
// first sync call for this Item. The first request will
// return a cursor.
let cursor = database.getLatestCursorOrNull(itemId);


// New transaction updates since "cursor"
let added: Array = [];
let modified: Array = [];
// Removed transaction ids
let removed: Array = [];
let hasMore = true;


// Iterate through each page of new transaction updates for item
while (hasMore) {
  const request: ProcessorTransactionsSyncRequest = {
    processor_token: processorToken,
    cursor: cursor,
  };
  const response = await client.processorTransactionsSync(request);
  const data = response.data;


  // Add this page of results
  added = added.concat(data.added);
  modified = modified.concat(data.modified);
  removed = removed.concat(data.removed);


  hasMore = data.has_more;


  // Update cursor to the next cursor
  cursor = data.next_cursor;
}


// Persist cursor and updated data
database.applyUpdates(itemId, added, modified, removed, cursor);
```

#### Response fields and example 

**transactions\_update\_status** (string)  
A description of the update status for transaction pulls of an Item. This field contains the same information provided by transactions webhooks, and may be helpful for webhook troubleshooting or when recovering from missed webhooks. TRANSACTIONS\_UPDATE\_STATUS\_UNKNOWN: Unable to fetch transactions update status for Item. NOT\_READY: The Item is pending transaction pull. INITIAL\_UPDATE\_COMPLETE: Initial pull for the Item is complete, historical pull is pending. HISTORICAL\_UPDATE\_COMPLETE: Both initial and historical pull for Item are complete. Possible values: TRANSACTIONS\_UPDATE\_STATUS\_UNKNOWN, NOT\_READY, INITIAL\_UPDATE\_COMPLETE, HISTORICAL\_UPDATE\_COMPLETE

**account** (nullable, object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**added** (\[object\])  
Transactions that have been added to the Item since cursor ordered by ascending last modified time.

**added->account\_id** (string)  
The ID of the account in which this transaction occurred.

**added->amount** (number)  
The settled value of the transaction, denominated in the transactions's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: double

**added->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**added->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**added->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**added->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized\_date field. Format: date

**added->location** (object)  
A representation of where a transaction took place

**added->location->address** (nullable, string)  
The street address where the transaction occurred.

**added->location->city** (nullable, string)  
The city where the transaction occurred.

**added->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**added->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**added->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**added->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**added->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**added->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**added->name** (deprecated, string)  
The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use merchant\_name instead for the merchant name. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**added->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**added->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field will only be included if the client has set options.include\_original\_description to true.

**added->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**added->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**added->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**added->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**added->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**added->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**added->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**added->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**added->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**added->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.

**added->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions.

**added->account\_owner** (nullable, string)  
This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution.

**added->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**added->transaction\_type** (deprecated, string)  
Please use the payment\_channel field, transaction\_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**added->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**added->website** (nullable, string)  
The website associated with this transaction, if available.

**added->authorized\_date** (nullable, string)  
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized\_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**added->authorized\_datetime** (nullable, string)  
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized\_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**added->datetime** (nullable, string)  
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized\_datetime field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**added->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. This field replaces the transaction\_type field. Possible values: online, in store, other

**added->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**added->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**added->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**added->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**added->transaction\_code** (nullable, string)  
An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. adjustment: Bank adjustment atm: Cash deposit or withdrawal via an automated teller machine bank charge: Charge or fee levied by the institution bill payment: Payment of a bill cash: Cash deposit or withdrawal cashback: Cash withdrawal while making a debit card purchase cheque: Document ordering the payment of money to another person or organization direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval interest: Interest earned or incurred purchase: Purchase made with a debit or credit card standing order: Payment instructed by the account holder to a third party at a regular interval transfer: Transfer of money between accounts Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null

**added->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**added->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**added->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**added->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**added->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**added->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**added->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**added->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**added->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**added->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**added->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**added->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**added->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**added->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**added->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**added->merchant\_entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store.

**modified** (\[object\])  
Transactions that have been modified on the Item since cursor ordered by ascending last modified time.

**modified->account\_id** (string)  
The ID of the account in which this transaction occurred.

**modified->amount** (number)  
The settled value of the transaction, denominated in the transactions's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: double

**modified->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**modified->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**modified->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**modified->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized\_date field. Format: date

**modified->location** (object)  
A representation of where a transaction took place

**modified->location->address** (nullable, string)  
The street address where the transaction occurred.

**modified->location->city** (nullable, string)  
The city where the transaction occurred.

**modified->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**modified->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**modified->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**modified->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**modified->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**modified->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**modified->name** (deprecated, string)  
The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use merchant\_name instead for the merchant name. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**modified->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**modified->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field will only be included if the client has set options.include\_original\_description to true.

**modified->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**modified->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**modified->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**modified->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**modified->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**modified->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**modified->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**modified->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**modified->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**modified->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.

**modified->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions.

**modified->account\_owner** (nullable, string)  
This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution.

**modified->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**modified->transaction\_type** (deprecated, string)  
Please use the payment\_channel field, transaction\_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**modified->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**modified->website** (nullable, string)  
The website associated with this transaction, if available.

**modified->authorized\_date** (nullable, string)  
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized\_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**modified->authorized\_datetime** (nullable, string)  
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized\_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**modified->datetime** (nullable, string)  
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized\_datetime field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**modified->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. This field replaces the transaction\_type field. Possible values: online, in store, other

**modified->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**modified->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**modified->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**modified->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**modified->transaction\_code** (nullable, string)  
An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. adjustment: Bank adjustment atm: Cash deposit or withdrawal via an automated teller machine bank charge: Charge or fee levied by the institution bill payment: Payment of a bill cash: Cash deposit or withdrawal cashback: Cash withdrawal while making a debit card purchase cheque: Document ordering the payment of money to another person or organization direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval interest: Interest earned or incurred purchase: Purchase made with a debit or credit card standing order: Payment instructed by the account holder to a third party at a regular interval transfer: Transfer of money between accounts Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null

**modified->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**modified->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**modified->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**modified->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**modified->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**modified->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**modified->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**modified->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**modified->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**modified->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**modified->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**modified->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**modified->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**modified->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**modified->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**modified->merchant\_entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store.

**removed** (\[object\])  
Transactions that have been removed from the Item since cursor ordered by ascending last modified time.

**removed->transaction\_id** (string)  
The ID of the removed transaction.

**removed->account\_id** (string)  
The ID of the account of the removed transaction.

**next\_cursor** (string)  
Cursor used for fetching any future updates after the latest update provided in this response. The cursor obtained after all pages have been pulled (indicated by has\_more being false) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string.

**has\_more** (boolean)  
Represents if more than requested count of transaction updates exist. If true, the additional updates can be fetched by making an additional request with cursor set to next\_cursor. If has\_more is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
    "balances": {
      "available": 110.94,
      "current": 110.94,
      "iso_currency_code": "USD",
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Standard 0% Interest Checking",
    "subtype": "checking",
    "type": "depository"
  },
  "added": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 72.1,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "Walmart",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
          "website": "walmart.com",
          "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-24",
      "datetime": "2023-09-24T11:01:01Z",
      "authorized_date": "2023-09-22",
      "authorized_datetime": "2023-09-22T10:34:50Z",
      "location": {
        "address": "13425 Community Rd",
        "city": "Poway",
        "region": "CA",
        "postal_code": "92064",
        "country": "US",
        "lat": 32.959068,
        "lon": -117.037666,
        "store_number": "1700"
      },
      "name": "PURCHASE WM SUPERCENTER #1700",
      "merchant_name": "Walmart",
      "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
      "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
      "website": "walmart.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "in store",
      "pending": false,
      "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "personal_finance_category": {
        "primary": "GENERAL_MERCHANDISE",
        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "transaction_code": null,
      "transaction_type": "place"
    }
  ],
  "modified": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 28.34,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "DoorDash",
          "type": "marketplace",
          "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",
          "website": "doordash.com",
          "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",
          "confidence_level": "HIGH"
        },
        {
          "name": "Burger King",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
          "website": "burgerking.com",
          "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-28",
      "datetime": "2023-09-28T15:10:09Z",
      "authorized_date": "2023-09-27",
      "authorized_datetime": "2023-09-27T08:01:58Z",
      "location": {
        "address": null,
        "city": null,
        "region": null,
        "postal_code": null,
        "country": null,
        "lat": null,
        "lon": null,
        "store_number": null
      },
      "name": "Dd Doordash Burgerkin",
      "merchant_name": "Burger King",
      "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
      "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
      "website": "burgerking.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "online",
      "pending": true,
      "pending_transaction_id": null,
      "personal_finance_category": {
        "primary": "FOOD_AND_DRINK",
        "detailed": "FOOD_AND_DRINK_FAST_FOOD",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",
      "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
      "transaction_code": null,
      "transaction_type": "digital"
    }
  ],
  "removed": [
    {
      "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l",
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
    }
  ],
  "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV",
  "has_more": false,
  "request_id": "45QSn",
  "transactions_update_status": "HISTORICAL_UPDATE_COMPLETE"
}
```

\=\*=\*=\*=

#### /processor/transactions/get 

#### Get transaction data 

The [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype `student`; coverage may be limited). Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.  
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) . For more details, see [Pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#pending-and-posted-transactions) .  
Due to the potentially large number of transactions associated with a processor token, results are paginated. Manipulate the `count` and `offset` parameters in conjunction with the `total_transactions` response body field to fetch all available transactions.  
Data returned by [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) will be the data available for the processor token as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To force Plaid to check for new transactions, you can use the [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) endpoint.  
Note that data may not be immediately available to [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) . Plaid will begin to prepare transactions data upon Item link, if Link was initialized with `transactions`, or upon the first call to [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , if it wasn't. If no transaction history is ready when [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) is called, it will return a `PRODUCT_NOT_READY` error.  
To receive Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint.

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

**options** (object)  
An optional object to be used with the request. If specified, options must not be null.

**options->count** (integer)  
The number of transactions to fetch. Default: 100 Minimum: 1 Maximum: 500 Exclusive min: false

**options->offset** (integer)  
The number of transactions to skip. The default value is 0. Default: 0 Minimum: 0

**options->include\_original\_description** (boolean)  
Include the raw unparsed transaction description from the financial institution. Default: false

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

**start\_date** (required, string)  
The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date

**end\_date** (required, string)  
The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date

```javascript
const request: ProcessorTransactionsGetRequest = {
  processor_token: processorToken,
  start_date: '2018-01-01',
  end_date: '2020-02-01'
};
try {
  const response = await client.processorTransactionsGet(request);
  let transactions = response.data.transactions;
  const total_transactions = response.data.total_transactions;
  // Manipulate the offset parameter to paginate
  // transactions and retrieve all available data
  while (transactions.length < total_transactions) {
    const paginatedRequest: ProcessorTransactionsGetRequest = {
      processor_token: processorToken,
      start_date: '2018-01-01',
      end_date: '2020-02-01',
      options: {
        offset: transactions.length,
      },
    };
    const paginatedResponse = await client.processorTransactionsGet(paginatedRequest);
    transactions = transactions.concat(
      paginatedResponse.data.transactions,
    );
  }
} catch((err) => {
  // handle error
}
```

#### Response fields and example 

**account** (object)  
A single account at a financial institution.

**account->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**account->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**account->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**account->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**account->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**account->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**account->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**account->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**account->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**account->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**account->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**account->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**account->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**account->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**account->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**account->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**account->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**account->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**account->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**account->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**account->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**account->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**account->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**account->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**account->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**transactions** (\[object\])  
An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter.

**transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**transactions->amount** (number)  
The settled value of the transaction, denominated in the transactions's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: double

**transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized\_date field. Format: date

**transactions->location** (object)  
A representation of where a transaction took place

**transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**transactions->name** (deprecated, string)  
The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use merchant\_name instead for the merchant name. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field will only be included if the client has set options.include\_original\_description to true.

**transactions->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**transactions->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**transactions->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**transactions->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**transactions->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**transactions->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**transactions->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**transactions->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**transactions->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.

**transactions->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions.

**transactions->account\_owner** (nullable, string)  
This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution.

**transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**transactions->transaction\_type** (deprecated, string)  
Please use the payment\_channel field, transaction\_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**transactions->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**transactions->website** (nullable, string)  
The website associated with this transaction, if available.

**transactions->authorized\_date** (nullable, string)  
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized\_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**transactions->authorized\_datetime** (nullable, string)  
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized\_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**transactions->datetime** (nullable, string)  
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized\_datetime field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**transactions->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. This field replaces the transaction\_type field. Possible values: online, in store, other

**transactions->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**transactions->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**transactions->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**transactions->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**transactions->transaction\_code** (nullable, string)  
An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. adjustment: Bank adjustment atm: Cash deposit or withdrawal via an automated teller machine bank charge: Charge or fee levied by the institution bill payment: Payment of a bill cash: Cash deposit or withdrawal cashback: Cash withdrawal while making a debit card purchase cheque: Document ordering the payment of money to another person or organization direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval interest: Interest earned or incurred purchase: Purchase made with a debit or credit card standing order: Payment instructed by the account holder to a third party at a regular interval transfer: Transfer of money between accounts Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null

**transactions->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**transactions->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**transactions->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**transactions->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**transactions->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**transactions->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**transactions->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**transactions->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**transactions->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**transactions->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**transactions->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**transactions->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**transactions->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**transactions->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**transactions->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**transactions->merchant\_entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store.

**total\_transactions** (integer)  
The total number of transactions available within the date range specified. If total\_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "account": {
    "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
    "balances": {
      "available": 110.94,
      "current": 110.94,
      "iso_currency_code": "USD",
      "limit": null,
      "unofficial_currency_code": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Standard 0% Interest Checking",
    "subtype": "checking",
    "type": "depository"
  },
  "transactions": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 28.34,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "DoorDash",
          "type": "marketplace",
          "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",
          "website": "doordash.com",
          "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",
          "confidence_level": "HIGH"
        },
        {
          "name": "Burger King",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
          "website": "burgerking.com",
          "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-28",
      "datetime": "2023-09-28T15:10:09Z",
      "authorized_date": "2023-09-27",
      "authorized_datetime": "2023-09-27T08:01:58Z",
      "location": {
        "address": null,
        "city": null,
        "region": null,
        "postal_code": null,
        "country": null,
        "lat": null,
        "lon": null,
        "store_number": null
      },
      "name": "Dd Doordash Burgerkin",
      "merchant_name": "Burger King",
      "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
      "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
      "website": "burgerking.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "online",
      "pending": true,
      "pending_transaction_id": null,
      "personal_finance_category": {
        "primary": "FOOD_AND_DRINK",
        "detailed": "FOOD_AND_DRINK_FAST_FOOD",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",
      "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
      "transaction_code": null,
      "transaction_type": "digital"
    },
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 72.1,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "Walmart",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
          "website": "walmart.com",
          "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-24",
      "datetime": "2023-09-24T11:01:01Z",
      "authorized_date": "2023-09-22",
      "authorized_datetime": "2023-09-22T10:34:50Z",
      "location": {
        "address": "13425 Community Rd",
        "city": "Poway",
        "region": "CA",
        "postal_code": "92064",
        "country": "US",
        "lat": 32.959068,
        "lon": -117.037666,
        "store_number": "1700"
      },
      "name": "PURCHASE WM SUPERCENTER #1700",
      "merchant_name": "Walmart",
      "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
      "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
      "website": "walmart.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "in store",
      "pending": false,
      "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "personal_finance_category": {
        "primary": "GENERAL_MERCHANDISE",
        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "transaction_code": null,
      "transaction_type": "place"
    }
  ],
  "total_transactions": 1,
  "request_id": "Wvhy9PZHQLV8njG"
}
```

\=\*=\*=\*=

#### /processor/transactions/recurring/get 

#### Fetch recurring transaction streams 

The [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments.  
This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager.  
This endpoint can only be called on a processor token that has already been initialized with Transactions (either during Link, by specifying it in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; or after Link, by calling [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) or [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) ). Once all historical transactions have been fetched, call [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) to receive the Recurring Transactions streams and subscribe to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook. To know when historical transactions have been fetched, if you are using [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#SyncUpdatesAvailableWebhook-historical-update-complete) webhook and check that the `historical_update_complete` field in the payload is `true`. If using [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , listen for the [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) webhook.  
After the initial call, you can call [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook to be notified when new updates are available.  
To receive Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

```javascript
const request: ProcessorTransactionsGetRequest = {
  processor_token: processorToken
};
try {
  const response = await client.processorTransactionsRecurringGet(request);
  let inflowStreams = response.data.inflowStreams;
  let outflowStreams = response.data.outflowStreams;
  }
} catch((err) => {
  // handle error
}
```

#### Response fields and example 

**inflow\_streams** (\[object\])  
An array of depository transaction streams.

**inflow\_streams->account\_id** (string)  
The ID of the account to which the stream belongs

**inflow\_streams->stream\_id** (string)  
A unique id for the stream

**inflow\_streams->description** (string)  
A description of the transaction stream.

**inflow\_streams->merchant\_name** (nullable, string)  
The merchant associated with the transaction stream.

**inflow\_streams->first\_date** (string)  
The posted date of the earliest transaction in the stream. Format: date

**inflow\_streams->last\_date** (string)  
The posted date of the latest transaction in the stream. Format: date

**inflow\_streams->predicted\_next\_date** (nullable, string)  
The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: date

**inflow\_streams->frequency** (string)  
Describes the frequency of the transaction stream. WEEKLY: Assigned to a transaction stream that occurs approximately every week. BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks. SEMI\_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. MONTHLY: Assigned to a transaction stream that occurs approximately every month. ANNUALLY: Assigned to a transaction stream that occurs approximately every year. UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, ANNUALLY

**inflow\_streams->transaction\_ids** (\[string\])  
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.

**inflow\_streams->average\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**inflow\_streams->average\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**inflow\_streams->average\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**inflow\_streams->average\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**inflow\_streams->last\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**inflow\_streams->last\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**inflow\_streams->last\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**inflow\_streams->last\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**inflow\_streams->is\_active** (boolean)  
Indicates whether the transaction stream is still live.

**inflow\_streams->status** (string)  
The current status of the transaction stream. MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances). EARLY\_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY\_DETECTION. TOMBSTONED: A stream that was previously in the EARLY\_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date. UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable. Possible values: UNKNOWN, MATURE, EARLY\_DETECTION, TOMBSTONED

**inflow\_streams->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**inflow\_streams->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**inflow\_streams->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**inflow\_streams->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**inflow\_streams->is\_user\_modified** (deprecated, boolean)  
As the ability to modify transactions streams has been discontinued, this field will always be false.

**outflow\_streams** (\[object\])  
An array of expense transaction streams.

**outflow\_streams->account\_id** (string)  
The ID of the account to which the stream belongs

**outflow\_streams->stream\_id** (string)  
A unique id for the stream

**outflow\_streams->description** (string)  
A description of the transaction stream.

**outflow\_streams->merchant\_name** (nullable, string)  
The merchant associated with the transaction stream.

**outflow\_streams->first\_date** (string)  
The posted date of the earliest transaction in the stream. Format: date

**outflow\_streams->last\_date** (string)  
The posted date of the latest transaction in the stream. Format: date

**outflow\_streams->predicted\_next\_date** (nullable, string)  
The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: date

**outflow\_streams->frequency** (string)  
Describes the frequency of the transaction stream. WEEKLY: Assigned to a transaction stream that occurs approximately every week. BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks. SEMI\_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. MONTHLY: Assigned to a transaction stream that occurs approximately every month. ANNUALLY: Assigned to a transaction stream that occurs approximately every year. UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, ANNUALLY

**outflow\_streams->transaction\_ids** (\[string\])  
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.

**outflow\_streams->average\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**outflow\_streams->average\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**outflow\_streams->average\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**outflow\_streams->average\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**outflow\_streams->last\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**outflow\_streams->last\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**outflow\_streams->last\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**outflow\_streams->last\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**outflow\_streams->is\_active** (boolean)  
Indicates whether the transaction stream is still live.

**outflow\_streams->status** (string)  
The current status of the transaction stream. MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances). EARLY\_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY\_DETECTION. TOMBSTONED: A stream that was previously in the EARLY\_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date. UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable. Possible values: UNKNOWN, MATURE, EARLY\_DETECTION, TOMBSTONED

**outflow\_streams->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**outflow\_streams->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**outflow\_streams->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**outflow\_streams->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**outflow\_streams->is\_user\_modified** (deprecated, boolean)  
As the ability to modify transactions streams has been discontinued, this field will always be false.

**updated\_datetime** (string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time transaction streams for the given account were updated on Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "updated_datetime": "2022-05-01T00:00:00Z",
  "inflow_streams": [
    {
      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "category": null,
      "category_id": null,
      "description": "Platypus Payroll",
      "merchant_name": null,
      "personal_finance_category": {
        "primary": "INCOME",
        "detailed": "INCOME_WAGES",
        "confidence_level": "UNKNOWN"
      },
      "first_date": "2022-02-28",
      "last_date": "2022-04-30",
      "predicted_next_date": "2022-05-15",
      "frequency": "SEMI_MONTHLY",
      "transaction_ids": [
        "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw",
        "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL",
        "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd",
        "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK",
        "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF"
      ],
      "average_amount": {
        "amount": -800,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "last_amount": {
        "amount": -1000,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "is_active": true,
      "status": "MATURE",
      "is_user_modified": false
    }
  ],
  "outflow_streams": [
    {
      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd",
      "category": null,
      "category_id": null,
      "description": "ConEd Bill Payment",
      "merchant_name": "ConEd",
      "personal_finance_category": {
        "primary": "RENT_AND_UTILITIES",
        "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY",
        "confidence_level": "UNKNOWN"
      },
      "first_date": "2022-02-04",
      "last_date": "2022-05-02",
      "predicted_next_date": "2022-06-02",
      "frequency": "MONTHLY",
      "transaction_ids": [
        "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
        "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR",
        "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L",
        "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
      ],
      "average_amount": {
        "amount": 85,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "last_amount": {
        "amount": 100,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "is_active": true,
      "status": "MATURE",
      "is_user_modified": false
    },
    {
      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
      "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC",
      "category": null,
      "category_id": null,
      "description": "Costco Annual Membership",
      "merchant_name": "Costco",
      "personal_finance_category": {
        "primary": "GENERAL_MERCHANDISE",
        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
        "confidence_level": "UNKNOWN"
      },
      "first_date": "2022-01-23",
      "last_date": "2023-01-22",
      "predicted_next_date": "2024-01-22",
      "frequency": "ANNUALLY",
      "transaction_ids": [
        "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4",
        "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ"
      ],
      "average_amount": {
        "amount": 120,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "last_amount": {
        "amount": 120,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "is_active": true,
      "status": "MATURE",
      "is_user_modified": false
    }
  ],
  "request_id": "tbFyCEqkU775ZGG"
}
```

\=\*=\*=\*=

#### /processor/transactions/refresh 

#### Refresh transaction data 

[/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for a processor token. This on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Transactions-enabled processor token. If changes to transactions are discovered after calling [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) , Plaid will fire a webhook: for [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) users, [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) will be fired if there are any transactions updated, added, or removed. For users of both [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) and [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) will be fired if any removed transactions are detected, and [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) will be fired if any new transactions are detected. New transactions can be fetched by calling [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) or [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) . Note that the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint is not supported for Capital One (`ins_128026`) non-depository accounts and will result in a `PRODUCTS_NOT_SUPPORTED` error if called on an Item that contains only non-depository accounts from that institution.  
As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests.  
[/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) is offered as an add-on to Transactions and has a separate [fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

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

```javascript
const request: ProcessorTransactionsRefreshRequest = {
  processor_token: processorToken,
};
try {
  await plaidClient.processorTransactionsRefresh(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "1vwmF5TBQwiqfwP"
}
```

Processor webhooks 
-------------------

\=\*=\*=\*=

#### WEBHOOK\_UPDATE\_ACKNOWLEDGED 

This webhook is only sent to [Plaid processor partners](https://plaid.com/docs/auth/partnerships/index.html.md) .  
Fired when a processor updates the webhook URL for a processor token via [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) .

#### Properties 

**webhook\_type** (string)  
PROCESSOR\_TOKEN

**webhook\_code** (string)  
WEBHOOK\_UPDATE\_ACKNOWLEDGED

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**account\_id** (string)  
The ID of the account.

**new\_webhook\_url** (string)  
The new webhook URL.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "PROCESSOR_TOKEN",
  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
  "new_webhook_url": "https://www.example.com",
  "error": null,
  "environment": "production"
}
```

---


# API - Processor tokens | Plaid Docs

Processor token endpoints 
==========================

#### API reference for endpoints for use with Plaid partners 

Processor token endpoints are used to create tokens that are then sent to a Plaid partner for use in a Plaid integration. For a full list of integrations, see the [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) . For specific information on Auth integrations, see [Auth payment partners](https://plaid.com/docs/auth/partnerships/index.html.md) .

Are you a Plaid processor partner looking for API docs? The documentation on API endpoints for use by partners has moved to [Processor partner endpoints](https://plaid.com/docs/api/processor-partners/index.html.md) .

| In this section |  |
| --- | --- |
| [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | Create a processor token |
| [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) | Create a bank account token for use with Stripe |
| [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) | Set product permissions for a processor token |
| [/processor/token/permissions/get](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsget) | Get product permissions for a processor token |

| See also |  |
| --- | --- |
| [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | Create a test Item and processor token (Sandbox only) |

\=\*=\*=\*=

#### /processor/token/create 

#### Create processor token 

Used to create a token suitable for sending to one of Plaid's partners to enable integrations. Note that Stripe partnerships use bank account tokens instead; see [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) for creating tokens for use with Stripe integrations. If using multiple processors, multiple different processor tokens can be created for a single access token. Once created, a processor token for a given Item cannot be modified or updated. To revoke the processor's access, the entire Item must be deleted by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**account\_id** (required, string)  
The account\_id value obtained from the onSuccess callback in Link

**processor** (required, string)  
The processor you are integrating with. Possible values: dwolla, galileo, modern\_treasury, ocrolus, vesta, drivewealth, vopay, achq, check, checkbook, circle, sila\_money, rize, svb\_api, unit, wyre, lithic, alpaca, astra, moov, treasury\_prime, marqeta, checkout, solid, highnote, gemini, apex\_clearing, gusto, adyen, atomic, i2c, wepay, riskified, utb, adp\_roll, fortress\_trust, bond, bakkt, teal, zero\_hash, taba\_pay, knot, sardine, alloy, finix, nuvei, layer, boom, paynote, stake, wedbush, esusu, ansa, scribeup, straddle, loanpro, bloom\_credit, sfox, brale, parafin, cardless, open\_ledger, valon, gainbridge

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
} = require('plaid');
// Change sandbox to development to test with live users;
// Change to production when you're ready to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: PUBLIC_TOKEN,
  });
  const accessToken = tokenResponse.data.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'dwolla',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.data.processor_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**processor\_token** (string)  
The processor\_token that can then be used by the Plaid partner to make API requests

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "xrQNYZ7Zoh6R7gV"
}
```

\=\*=\*=\*=

#### /processor/token/permissions/set 

#### Control a processor's access to products 

Used to control a processor's access to products on the given processor token. By default, a processor will have access to all available products on the corresponding item. To restrict access to a particular set of products, call this endpoint with the desired products. To restore access to all available products, call this endpoint with an empty list. This endpoint can be called multiple times as your needs and your processor's needs change.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

**products** (required, \[string\])  
A list of products the processor token should have access to. An empty list will grant access to all products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

```javascript
try {
  const request: ProcessorTokenPermissionsSetRequest = {
    processor_token: processorToken,
    products: ['auth', 'balance', 'identity'],
  };
  const response = await plaidClient.processorTokenPermissionsSet(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "xrQNYZ7Zoh6R7gV"
}
```

\=\*=\*=\*=

#### /processor/token/permissions/get 

#### Get a processor token's product permissions 

Used to get a processor token's product permissions. The `products` field will be an empty list if the processor can access all available products.

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

**processor\_token** (required, string)  
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor--

```javascript
try {
  const request: ProcessorTokenPermissionsGetRequest = {
    processor_token: processorToken,
  };
  const response = await plaidClient.processorTokenPermissionsGet(request);
  const products = response.data.products;
} catch (error) {
  // handle error
}
```

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

**products** (\[string\])  
A list of products the processor token should have access to. An empty list means that the processor has access to all available products, including future products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

```json
{
  "request_id": "xrQNYZ7Zoh6R7gV",
  "products": [
    "auth",
    "balance",
    "identity"
  ]
}
```

\=\*=\*=\*=

#### /processor/stripe/bank\_account\_token/create 

#### Create Stripe bank account token 

Used to create a token suitable for sending to Stripe to enable Plaid-Stripe integrations. For a detailed guide on integrating Stripe, see [Add Stripe to your app](https://plaid.com/docs/auth/partnerships/stripe/index.html.md) .  
Note that the Stripe bank account token is a one-time use token. To store bank account information for later use, you can use a Stripe customer object and create an associated bank account from the token, or you can use a Stripe Custom account and create an associated external bank account from the token. This bank account information should work indefinitely, unless the user's bank account information changes or they revoke Plaid's permissions to access their account. Stripe bank account information cannot be modified once the bank account token has been created. If you ever need to change the bank account details used by Stripe for a specific customer, have the user go through Link again and create a new bank account token from the new `access_token`.  
To revoke a bank account token, the entire underlying access token must be revoked using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**account\_id** (required, string)  
The account\_id value obtained from the onSuccess callback in Link

```javascript
// Change sandbox to development to test with live users and change
// to production when you're ready to go live!
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorStripeBankAccountTokenCreateRequest,
} = require('plaid');
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: PUBLIC_TOKEN,
  });
  const accessToken = tokenResponse.data.access_token;


  // Generate a bank account token
  const request: ProcessorStripeBankAccountTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
  };
  const stripeTokenResponse = await plaidClient.processorStripeBankAccountTokenCreate(
    request,
  );
  const bankAccountToken = stripeTokenResponse.data.stripe_bank_account_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**stripe\_bank\_account\_token** (string)  
A token that can be sent to Stripe for use in making API calls to Plaid

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",
  "request_id": "xrQNYZ7Zoh6R7gV"
}
```

---


# API - Assets | Plaid Docs

Assets 
=======

#### API reference for Assets endpoints and webhooks 

Create, delete, retrieve and share Asset Reports with information about a user's assets and transactions. For how-to guidance on Asset Reports, see the [Assets documentation](https://plaid.com/docs/assets/index.html.md) .

All the endpoints on this page are also compatible with [Financial Insights Reports (UK/EU only)](https://plaid.com/docs/assets/index.html.md#financial-insights-reports-ukeu-only) and will automatically operate on Financial Insights Reports instead of Asset Reports if the Financial Insights Report add-on has been enabled.

| Endpoints |  |
| --- | --- |
| [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) | Create an Asset Report |
| [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) | Get an Asset Report |
| [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) | Get a PDF Asset Report |
| [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) | Create an updated Asset Report |
| [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) | Filter unneeded accounts from an Asset Report |
| [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) | Delete an asset report |
| [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) | Create an Audit Copy of an Asset Report for sharing |
| [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) | Delete an Audit Copy of an Asset Report |
| [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) | Create a relay token of an Asset Report for sharing (beta) |
| [/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) | Retrieve the report associated with a relay token (beta) |
| [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) | Refresh a report of a relay token (beta) |
| [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) | Delete a relay token (beta) |

| Webhooks |  |
| --- | --- |
| [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) | Asset Report generation has completed |
| [ERROR](https://plaid.com/docs/api/products/assets/index.html.md#error) | Asset Report generation has failed |

### Endpoints 

\=\*=\*=\*=

#### /asset\_report/create 

#### Create an Asset Report 

The [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the `asset_report_token` return value to the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) endpoints.  
The Asset Report takes some time to be created and is not available immediately after calling [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) . The exact amount of time to create the report will vary depending on how many days of history are requested and will typically range from a few seconds to about one minute. When the Asset Report is ready to be retrieved using [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) , Plaid will fire a `PRODUCT_READY` webhook. For full details of the webhook schema, see [Asset Report webhooks](https://plaid.com/docs/api/products/assets/index.html.md#webhooks) .  
The [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint.

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

**access\_tokens** (\[string\])  
An array of access tokens corresponding to the Items that will be included in the report. The assets product must have been initialized for the Items during link; the Assets product cannot be added after initialization. Min items: 1 Max items: 99

**days\_requested** (required, integer)  
The maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, days\_requested must be at least 61 for new originations or at least 31 for refinancings. An Asset Report requested with "Additional History" (that is, with more than 61 days of transaction history) will incur an Additional History fee. Maximum: 731 Minimum: 0

**options** (object)  
An optional object to filter /asset\_report/create results. If provided, must be non-null. The optional user object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program.

**options->client\_report\_id** (string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**options->webhook** (string)  
URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.

**options->add\_ons** (\[string\])  
A list of add-ons that should be included in the Asset Report. When Fast Assets is requested, Plaid will create two versions of the Asset Report: the Fast Asset Report, which will contain only Identity and Balance information, and the Full Asset Report, which will also contain Transactions information. A PRODUCT\_READY webhook will be fired for each Asset Report when it is ready, and the report\_type field will indicate whether the webhook is firing for the full or fast Asset Report. To retrieve the Fast Asset Report, call /asset\_report/get with fast\_report set to true. There is no additional charge for using Fast Assets. To create a Fast Asset Report, Plaid must successfully retrieve both Identity and Balance data; if Plaid encounters an error obtaining this data, the Fast Asset Report will not be created. However, as long as Plaid can obtain Transactions data, the Full Asset Report will still be available. When Investments is requested, investments must be specified in the optional\_products array when initializing Link. Possible values: investments, fast\_assets

**options->user** (object)  
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first\_name, last\_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.

**options->user->client\_user\_id** (string)  
An identifier you determine and submit for the user. If using the Credit Dashboard, Customers should pass in the user\_token created in /user/create.

**options->user->first\_name** (string)  
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.

**options->user->middle\_name** (string)  
The user's middle name

**options->user->last\_name** (string)  
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.

**options->user->ssn** (string)  
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"

**options->user->phone\_number** (string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.

**options->user->email** (string)  
The user's email address.

**options->require\_all\_items** (boolean)  
If set to false, only 1 item must be healthy at the time of report creation. The default value is true, which would require all items to be healthy at the time of report creation. Default: true

```javascript
const daysRequested = 90;
const options = {
  client_report_id: '123',
  webhook: 'https://www.example.com',
  user: {
    client_user_id: '7f57eb3d2a9j6480121fx361',
    first_name: 'Jane',
    middle_name: 'Leah',
    last_name: 'Doe',
    ssn: '123-45-6789',
    phone_number: '(555) 123-4567',
    email: 'jane.doe@example.com',
  },
};
const request: AssetReportCreateRequest = {
  access_tokens: [accessToken],
  days_requested,
  options,
};
// accessTokens is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
try {
  const response = await plaidClient.assetReportCreate(request);
  const assetReportId = response.data.asset_report_id;
  const assetReportToken = response.data.asset_report_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**asset\_report\_token** (string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**asset\_report\_id** (string)  
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
  "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
  "request_id": "Iam3b"
}
```

\=\*=\*=\*=

#### /asset\_report/get 

#### Retrieve an Asset Report 

The [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint retrieves the Asset Report in JSON format. Before calling [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) , you must first create the Asset Report using [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) (or filter an Asset Report using [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) ) and then wait for the [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook to fire, indicating that the Report is ready to be retrieved.  
By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid. You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report. To retrieve an Asset Report with Insights, call [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint with `include_insights` set to `true`.  
For latency-sensitive applications, you can optionally call [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) with `options.add_ons` set to `["fast_assets"]`. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report.

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

**asset\_report\_token** (string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**include\_insights** (boolean)  
true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted. Default: false

**fast\_report** (boolean)  
true to fetch "fast" version of asset report. Defaults to false if omitted. Can only be used if /asset\_report/create was called with options.add\_ons set to \["fast\_assets"\]. Default: false

**options** (object)  
An optional object to filter or add data to /asset\_report/get results. If provided, must be non-null.

**options->days\_to\_include** (integer)  
The maximum number of days of history to include in the Asset Report. Maximum: 731 Minimum: 0

```javascript
const request: request = {
  asset_report_token: assetReportToken,
  include_insights: true,
};
try {
  const response = await plaidClient.assetReportGet(request);
  const assetReportId = response.data.asset_report_id;
} catch (error) {
  if (error.data.error_code == 'PRODUCT_NOT_READY') {
    // Asset report is not ready yet. Try again later
  } else {
    // handle error
  }
}
```

#### Response fields and example 

**report** (object)  
An object representing an Asset Report

**report->asset\_report\_id** (string)  
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.

**report->client\_report\_id** (nullable, string)  
An identifier you determine and submit for the Asset Report.

**report->date\_generated** (string)  
The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time

**report->days\_requested** (number)  
The duration of transaction history you requested

**report->user** (object)  
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first\_name, last\_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.

**report->user->client\_user\_id** (nullable, string)  
An identifier you determine and submit for the user. If using the Credit Dashboard, Customers should pass in the user\_token created in /user/create.

**report->user->first\_name** (nullable, string)  
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.

**report->user->middle\_name** (nullable, string)  
The user's middle name

**report->user->last\_name** (nullable, string)  
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.

**report->user->ssn** (nullable, string)  
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"

**report->user->phone\_number** (nullable, string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.

**report->user->email** (nullable, string)  
The user's email address.

**report->items** (\[object\])  
Data returned by Plaid about each of the Items included in the Asset Report.

**report->items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**report->items->institution\_name** (string)  
The full financial institution name associated with the Item.

**report->items->institution\_id** (string)  
The id of the financial institution associated with the Item.

**report->items->date\_last\_updated** (string)  
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format. Format: date-time

**report->items->accounts** (\[object\])  
Data about each of the accounts open on the Item.

**report->items->accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->items->accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**report->items->accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**report->items->accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**report->items->accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**report->items->accounts->balances->margin\_loan\_amount** (nullable, number)  
The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: double

**report->items->accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->items->accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get. This field is only used and expected when the institution is ins\_128026 (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID\_REQUEST error with the code of INVALID\_FIELD will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an INVALID\_REQUEST error with the code of LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE will be returned with the most recent timestamp for the requested account contained in the response. Format: date-time

**report->items->accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**report->items->accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**report->items->accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**report->items->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**report->items->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**report->items->accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only. 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 micro-deposit. 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. database\_matched: The Item has successfully been verified using Plaid's data sources. Note: Database Match is currently a beta feature, please contact your account manager for more information. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, manually\_verified, verification\_expired, verification\_failed, database\_matched

**report->items->accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.

**report->items->accounts->days\_available** (number)  
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.

**report->items->accounts->transactions** (\[object\])  
Transaction history associated with the account.

**report->items->accounts->transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**report->items->accounts->transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: double

**report->items->accounts->transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->items->accounts->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**report->items->accounts->transactions->category** (nullable, \[string\])  
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get. This field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->category\_id** (nullable, string)  
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get. This field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->credit\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the taxonomy csv file for a full list of credit categories.

**report->items->accounts->transactions->credit\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**report->items->accounts->transactions->credit\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**report->items->accounts->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**report->items->accounts->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**report->items->accounts->transactions->date\_transacted** (nullable, string)  
The date on which the transaction took place, in IS0 8601 format.

**report->items->accounts->transactions->location** (object)  
A representation of where a transaction took place

**report->items->accounts->transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**report->items->accounts->transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**report->items->accounts->transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**report->items->accounts->transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**report->items->accounts->transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**report->items->accounts->transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**report->items->accounts->transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**report->items->accounts->transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**report->items->accounts->transactions->name** (deprecated, string)  
The merchant name or transaction description. This is a legacy field that is no longer maintained. For merchant name, use the merchant\_name field. For description, use the original\_description field. This field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**report->items->accounts->transactions->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**report->items->accounts->transactions->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**report->items->accounts->transactions->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**report->items->accounts->transactions->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**report->items->accounts->transactions->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**report->items->accounts->transactions->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**report->items->accounts->transactions->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**report->items->accounts->transactions->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**report->items->accounts->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->items->accounts->transactions->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable.

**report->items->accounts->transactions->account\_owner** (nullable, string)  
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.

**report->items->accounts->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->items->accounts->transactions->transaction\_type** (string)  
digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**report->items->accounts->investments** (object)  
A set of fields describing the investments data on an account.

**report->items->accounts->investments->holdings** (\[object\])  
Quantities and values of securities held in the investment account. Map to the securities array for security details.

**report->items->accounts->investments->holdings->account\_id** (string)  
The Plaid account\_id associated with the holding.

**report->items->accounts->investments->holdings->security\_id** (string)  
The Plaid security\_id associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The security\_id for the same security will typically be the same across different institutions, but this is not guaranteed. The security\_id does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**report->items->accounts->investments->holdings->ticker\_symbol** (nullable, string)  
The holding's trading symbol for publicly traded holdings, and otherwise a short identifier if available.

**report->items->accounts->investments->holdings->institution\_price** (number)  
The last price given by the institution for this security. Format: double

**report->items->accounts->investments->holdings->institution\_price\_as\_of** (nullable, string)  
The date at which institution\_price was current. Format: date

**report->items->accounts->investments->holdings->institution\_value** (number)  
The value of the holding, as reported by the institution. Format: double

**report->items->accounts->investments->holdings->cost\_basis** (nullable, number)  
The original total value of the holding. This field is calculated by Plaid as the sum of the purchase price of all of the shares in the holding. Format: double

**report->items->accounts->investments->holdings->quantity** (number)  
The total quantity of the asset held, as reported by the financial institution. If the security is an option, quantity will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: double

**report->items->accounts->investments->holdings->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the holding. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->investments->holdings->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**report->items->accounts->investments->securities** (\[object\])  
Details of specific securities held in on the investment account.

**report->items->accounts->investments->securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**report->items->accounts->investments->securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**report->items->accounts->investments->securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**report->items->accounts->investments->securities->type** (nullable, string)  
The security type of the holding. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**report->items->accounts->investments->transactions** (\[object\])  
Transaction history on the investment account.

**report->items->accounts->investments->transactions->investment\_transaction\_id** (string)  
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment\_transaction\_id is case sensitive.

**report->items->accounts->investments->transactions->account\_id** (string)  
The account\_id of the account against which this transaction posted.

**report->items->accounts->investments->transactions->security\_id** (nullable, string)  
The security\_id to which this transaction is related.

**report->items->accounts->investments->transactions->date** (string)  
The ISO 8601 posting date for the transaction. Format: date

**report->items->accounts->investments->transactions->name** (string)  
The institution’s description of the transaction.

**report->items->accounts->investments->transactions->quantity** (number)  
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: double

**report->items->accounts->investments->transactions->vested\_quantity** (number)  
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities. Format: double

**report->items->accounts->investments->transactions->vested\_value** (number)  
The value of the vested holdings as reported by the institution. Format: double

**report->items->accounts->investments->transactions->amount** (number)  
The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: double

**report->items->accounts->investments->transactions->price** (number)  
The price of the security at which this transaction occurred. Format: double

**report->items->accounts->investments->transactions->fees** (nullable, number)  
The combined value of all fees applied to this transaction Format: double

**report->items->accounts->investments->transactions->type** (string)  
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: buy, sell, cancel, cash, fee, transfer

**report->items->accounts->investments->transactions->subtype** (string)  
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal

**report->items->accounts->investments->transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->investments->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**report->items->accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners.For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning

**report->items->accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**report->items->accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->phone\_numbers->data** (string)  
The phone number.

**report->items->accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**report->items->accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**report->items->accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->emails->data** (string)  
The email address.

**report->items->accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**report->items->accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**report->items->accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**report->items->accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**report->items->accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**report->items->accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**report->items->accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**report->items->accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**report->items->accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**report->items->accounts->ownership\_type** (nullable, string)  
How an asset is owned. association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust. Possible values: null, individual, joint, association, trust

**report->items->accounts->historical\_balances** (\[object\])  
Calculated data about the historical balances on the account.

**report->items->accounts->historical\_balances->date** (string)  
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD) Format: date

**report->items->accounts->historical\_balances->current** (number)  
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction. If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting. Format: double

**report->items->accounts->historical\_balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->historical\_balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**warnings** (\[object\])  
If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing

**warnings->warning\_type** (string)  
The warning type, which will always be ASSET\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. OWNERS\_UNAVAILABLE indicates that account-owner information is not available.INVESTMENTS\_UNAVAILABLE indicates that Investments specific information is not available. TRANSACTIONS\_UNAVAILABLE indicates that transactions information associated with Credit and Depository accounts are unavailable. Possible values: OWNERS\_UNAVAILABLE, INVESTMENTS\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "report": {
    "asset_report_id": "028e8404-a013-4a45-ac9e-002482f9cafc",
    "client_report_id": "client_report_id_1221",
    "date_generated": "2023-03-30T18:27:37Z",
    "days_requested": 90,
    "items": [
      {
        "accounts": [
          {
            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
            "balances": {
              "available": 43200,
              "current": 43200,
              "limit": null,
              "margin_loan_amount": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            },
            "days_available": 90,
            "historical_balances": [
              {
                "current": 49050,
                "date": "2023-03-29",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-27",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-26",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-25",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "4444",
            "name": "Plaid Money Market",
            "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "+1 111-555-3333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "+1 111-555-4444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "+1 111-555-5555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "money market",
            "transactions": [
              {
                "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
                "amount": 5850,
                "date": "2023-03-30",
                "iso_currency_code": "USD",
                "original_description": "ACH Electronic CreditGUSTO PAY 123456",
                "pending": false,
                "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
            "balances": {
              "available": 100,
              "current": 110,
              "limit": null,
              "margin_loan_amount": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            },
            "days_available": 90,
            "historical_balances": [
              {
                "current": 110,
                "date": "2023-03-29",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -390,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -373.67,
                "date": "2023-03-27",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -284.27,
                "date": "2023-03-26",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -284.27,
                "date": "2023-03-25",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "+1 111-555-3333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "+1 111-555-4444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "+1 111-555-5555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "checking",
            "transactions": [
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": 89.4,
                "date": "2023-03-27",
                "iso_currency_code": "USD",
                "original_description": "SparkFun",
                "pending": false,
                "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": 12,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "original_description": "McDonalds #3322",
                "pending": false,
                "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL",
                "unofficial_currency_code": null
              },
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": 4.33,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "original_description": "Starbucks",
                "pending": false,
                "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy",
                "unofficial_currency_code": null
              },
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": -500,
                "date": "2023-03-29",
                "iso_currency_code": "USD",
                "original_description": "United Airlines **** REFUND ****",
                "pending": false,
                "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2023-03-30T18:25:26Z",
        "institution_id": "ins_109508",
        "institution_name": "First Platypus Bank",
        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7"
      }
    ],
    "user": {
      "client_user_id": "uid_40332",
      "email": "abcharleston@example.com",
      "first_name": "Anna",
      "last_name": "Charleston",
      "middle_name": "B",
      "phone_number": "1-415-867-5309",
      "ssn": "111-22-1234"
    }
  },
  "request_id": "GVzMdiDd8DDAQK4",
  "warnings": []
}
```

\=\*=\*=\*=

#### /asset\_report/pdf/get 

#### Retrieve a PDF Asset Report 

The [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) endpoint retrieves the Asset Report in PDF format. Before calling [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) , you must first create the Asset Report using [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) (or filter an Asset Report using [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) ) and then wait for the [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook to fire, indicating that the Report is ready to be retrieved.  
The response to [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) is the PDF binary data. The `request_id` is returned in the `Plaid-Request-ID` header.  
[View a sample PDF Asset Report](https://plaid.com/documents/sample-asset-report.pdf) .

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

**asset\_report\_token** (required, string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**options** (object)  
An optional object to filter or add data to /asset\_report/get results. If provided, must be non-null.

**options->days\_to\_include** (integer)  
The maximum integer number of days of history to include in the Asset Report. Maximum: 731 Minimum: 0

```javascript
try {
  const request: AssetReportPDFGetRequest = {
    asset_report_token: assetReportToken,
  };
  const response = await plaidClient.assetReportPdfGet(request, {
    responseType: 'arraybuffer',
  });
  const pdf = response.buffer.toString('base64');
} catch (error) {
  // handle error
}
```

##### Response 

This endpoint returns binary PDF data. [View a sample Asset Report PDF.](https://plaid.com/documents/sample-asset-report.pdf) . [View a sample Financial Insights Report (UK/EU only) PDF](https://plaid.com/documents/sample-financial-insights-report.pdf) .

\=\*=\*=\*=

#### /asset\_report/refresh 

#### Refresh an Asset Report 

An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint to create a new Asset Report based on the old one, but with the most recent data available.  
The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) . By default, the new Asset Report will also use the same parameters you submitted with your original [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) request, but the original `days_requested` value and the values of any parameters in the `options` object can be overridden with new values. To change these arguments, simply supply new values for them in your request to [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) . Submit an empty string ("") for any previously-populated fields you would like set as empty.

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

**asset\_report\_token** (required, string)  
The asset\_report\_token returned by the original call to /asset\_report/create

**days\_requested** (integer)  
The maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to /asset\_report/create will be used. Minimum: 0 Maximum: 731

**options** (object)  
An optional object to filter /asset\_report/refresh results. If provided, cannot be null. If not specified, the options from the original call to /asset\_report/create will be used.

**options->client\_report\_id** (string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**options->webhook** (string)  
URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.

**options->user** (object)  
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first\_name, last\_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.

**options->user->client\_user\_id** (string)  
An identifier you determine and submit for the user. If using the Credit Dashboard, Customers should pass in the user\_token created in /user/create.

**options->user->first\_name** (string)  
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.

**options->user->middle\_name** (string)  
The user's middle name

**options->user->last\_name** (string)  
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.

**options->user->ssn** (string)  
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"

**options->user->phone\_number** (string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.

**options->user->email** (string)  
The user's email address.

```javascript
const request: AssetReportRefreshRequest = {
  asset_report_token: assetReportToken,
  daysRequested: 90,
  options: {
    client_report_id: '123',
    webhook: 'https://www.example.com',
    user: {
      client_user_id: '7f57eb3d2a9j6480121fx361',
      first_name: 'Jane',
      middle_name: 'Leah',
      last_name: 'Doe',
      ssn: '123-45-6789',
      phone_number: '(555) 123-4567',
      email: 'jane.doe@example.com',
    },
  },
};
try {
  const response = await plaidClient.assetReportRefresh(request);
  const assetReportId = response.data.asset_report_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**asset\_report\_id** (string)  
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.

**asset\_report\_token** (string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}
```

\=\*=\*=\*=

#### /asset\_report/filter 

#### Filter Asset Report 

By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint. To narrow an Asset Report to only a subset of accounts, use the [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) endpoint.  
To exclude certain Accounts from an Asset Report, first use the [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint to create the report, then send the `asset_report_token` along with a list of `account_ids` to exclude to the [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data.  
Because Asset Reports are immutable, calling [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) does not alter the original Asset Report in any way; rather, [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) creates a new Asset Report with a new token and id. Asset Reports created via [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) do not contain new Asset data, and are not billed.  
Plaid will fire a [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook once generation of the filtered Asset Report has completed.

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

**asset\_report\_token** (required, string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**account\_ids\_to\_exclude** (required, \[string\])  
The accounts to exclude from the Asset Report, identified by account\_id.

```javascript
const request: AssetReportFilterRequest = {
  asset_report_token: assetReportToken,
  account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'],
};
try {
  const response = await plaidClient.assetReportFilter(request);
  const assetReportId = response.data.asset_report_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**asset\_report\_token** (string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**asset\_report\_id** (string)  
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
  "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
  "request_id": "qEg07"
}
```

\=\*=\*=\*=

#### /asset\_report/remove 

#### Delete an Asset Report 

The [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) endpoint allows you to invalidate an `access_token`, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically.  
The [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) endpoint allows you to remove access to an Asset Report. Removing an Asset Report invalidates its `asset_report_token`, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does invalidate any `audit_copy_tokens` associated with the Asset Report.

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

**asset\_report\_token** (required, string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

```javascript
const request: AssetReportRemoveRequest = {
  asset_report_token: assetReportToken,
};
try {
  const response = await plaidClient.assetReportRemove(request);
  const removed = response.data.removed;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**removed** (boolean)  
true if the Asset Report was successfully removed.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "removed": true,
  "request_id": "I6zHN"
}
```

\=\*=\*=\*=

#### /asset\_report/audit\_copy/create 

#### Create Asset Report Audit Copy 

Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can supply an Audit Copy directly to Fannie Mae on your behalf if you participate in the Day 1 Certainty™ program. An Audit Copy contains the same underlying data as the Asset Report.  
To grant access to an Audit Copy, use the [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) endpoint to create an `audit_copy_token` and then pass that token to the third party who needs access. Each third party has its own `auditor_id`, for example `fannie_mae`. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report.

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

**asset\_report\_token** (required, string)  
A token that can be provided to endpoints such as /asset\_report/get or /asset\_report/pdf/get to fetch or update an Asset Report.

**auditor\_id** (string)  
The auditor\_id of the third party with whom you would like to share the Asset Report.

```javascript
// The auditor ID corresponds to the third party with which you want to share
// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
const request: AssetReportAuditCopyCreateRequest = {
  asset_report_token: createResponse.data.asset_report_token,
  auditor_id: 'fannie_mae',
};
try {
  const response = await plaidClient.assetReportAuditCopyCreate(request);
  const auditCopyToken = response.data.audit_copy_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**audit\_copy\_token** (string)  
A token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
  "request_id": "Iam3b"
}
```

\=\*=\*=\*=

#### /asset\_report/audit\_copy/remove 

#### Remove Asset Report Audit Copy 

The [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the `audit_copy_token` associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy.

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

**audit\_copy\_token** (required, string)  
The audit\_copy\_token granting access to the Audit Copy you would like to revoke.

```javascript
// auditCopyToken is the token from the createAuditCopy response.
const request: AssetReportAuditCopyRemoveRequest = {
  audit_copy_token: auditCopyToken,
};
try {
  const response = await plaidClient.assetReportAuditCopyRemove(request);
  const removed = response.data.removed;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**removed** (boolean)  
true if the Audit Copy was successfully removed.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "removed": true,
  "request_id": "m8MDnv9okwxFNBV"
}
```

\=\*=\*=\*=

#### /credit/relay/create 

#### Create a relay token to share an Asset Report with a partner client 

Plaid can share an Asset Report directly with a participating third party on your behalf. The shared Asset Report is the exact same Asset Report originally created in [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) .  
To grant a third party access to an Asset Report, use the [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) endpoint to create a `relay_token` and then pass that token to your third party. Each third party has its own `secondary_client_id`; for example, `ce5bd328dcd34123456`. You'll need to create a separate `relay_token` for each third party that needs access to the report on your behalf.

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

**report\_tokens** (required, \[string\])  
List of report token strings, with at most one token of each report type. Currently only Asset Report token is supported.

**secondary\_client\_id** (required, string)  
The secondary\_client\_id is the client id of the third party with whom you would like to share the relay token.

**webhook** (string)  
URL to which Plaid will send webhooks when the Secondary Client successfully retrieves an Asset Report by calling /credit/relay/get.

```javascript
const request: CreditRelayCreateRequest = {
  report_tokens: [createResponse.data.asset_report_token],
  secondary_client_id: clientIdFromPartner
};
try {
  const response = await plaidClient.creditRelayCreate(request);
  const relayToken = response.data.relay_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**relay\_token** (string)  
A token that can be shared with a third party to allow them to access the Asset Report. This token should be stored securely.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "relay_token": "credit-relay-production-3TAU2CWVYBDVRHUCAAAI27ULU4",
  "request_id": "Iam3b"
}
```

\=\*=\*=\*=

#### /credit/relay/get 

#### Retrieve the reports associated with a relay token that was shared with you 

[/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) allows third parties to receive a report that was shared with them, using a `relay_token` that was created by the report owner.

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

**relay\_token** (required, string)  
The relay\_token granting access to the report you would like to get.

**report\_type** (required, string)  
The report type. It can be asset. Income report types are not yet supported. Possible values: asset

**include\_insights** (boolean)  
true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted. Default: false

```javascript
const request: CreditRelayGetRequest = {
  relay_token: createResponse.data.relay_token,
  report_type: 'assets',
};
try {
  const response = await plaidClient.creditRelayGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**report** (object)  
An object representing an Asset Report

**report->asset\_report\_id** (string)  
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.

**report->client\_report\_id** (nullable, string)  
An identifier you determine and submit for the Asset Report.

**report->date\_generated** (string)  
The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time

**report->days\_requested** (number)  
The duration of transaction history you requested

**report->user** (object)  
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first\_name, last\_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.

**report->user->client\_user\_id** (nullable, string)  
An identifier you determine and submit for the user. If using the Credit Dashboard, Customers should pass in the user\_token created in /user/create.

**report->user->first\_name** (nullable, string)  
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.

**report->user->middle\_name** (nullable, string)  
The user's middle name

**report->user->last\_name** (nullable, string)  
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.

**report->user->ssn** (nullable, string)  
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"

**report->user->phone\_number** (nullable, string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.

**report->user->email** (nullable, string)  
The user's email address.

**report->items** (\[object\])  
Data returned by Plaid about each of the Items included in the Asset Report.

**report->items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**report->items->institution\_name** (string)  
The full financial institution name associated with the Item.

**report->items->institution\_id** (string)  
The id of the financial institution associated with the Item.

**report->items->date\_last\_updated** (string)  
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format. Format: date-time

**report->items->accounts** (\[object\])  
Data about each of the accounts open on the Item.

**report->items->accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->items->accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**report->items->accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**report->items->accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**report->items->accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**report->items->accounts->balances->margin\_loan\_amount** (nullable, number)  
The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: double

**report->items->accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->items->accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get. This field is only used and expected when the institution is ins\_128026 (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID\_REQUEST error with the code of INVALID\_FIELD will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an INVALID\_REQUEST error with the code of LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE will be returned with the most recent timestamp for the requested account contained in the response. Format: date-time

**report->items->accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**report->items->accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**report->items->accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**report->items->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**report->items->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**report->items->accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only. 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 micro-deposit. 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. database\_matched: The Item has successfully been verified using Plaid's data sources. Note: Database Match is currently a beta feature, please contact your account manager for more information. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, manually\_verified, verification\_expired, verification\_failed, database\_matched

**report->items->accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.

**report->items->accounts->days\_available** (number)  
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.

**report->items->accounts->transactions** (\[object\])  
Transaction history associated with the account.

**report->items->accounts->transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**report->items->accounts->transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: double

**report->items->accounts->transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->items->accounts->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**report->items->accounts->transactions->category** (nullable, \[string\])  
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get. This field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->category\_id** (nullable, string)  
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get. This field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->credit\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the taxonomy csv file for a full list of credit categories.

**report->items->accounts->transactions->credit\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**report->items->accounts->transactions->credit\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**report->items->accounts->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**report->items->accounts->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**report->items->accounts->transactions->date\_transacted** (nullable, string)  
The date on which the transaction took place, in IS0 8601 format.

**report->items->accounts->transactions->location** (object)  
A representation of where a transaction took place

**report->items->accounts->transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**report->items->accounts->transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**report->items->accounts->transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**report->items->accounts->transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**report->items->accounts->transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**report->items->accounts->transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**report->items->accounts->transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**report->items->accounts->transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**report->items->accounts->transactions->name** (deprecated, string)  
The merchant name or transaction description. This is a legacy field that is no longer maintained. For merchant name, use the merchant\_name field. For description, use the original\_description field. This field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**report->items->accounts->transactions->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**report->items->accounts->transactions->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**report->items->accounts->transactions->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**report->items->accounts->transactions->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**report->items->accounts->transactions->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**report->items->accounts->transactions->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**report->items->accounts->transactions->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**report->items->accounts->transactions->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**report->items->accounts->transactions->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**report->items->accounts->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->items->accounts->transactions->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable.

**report->items->accounts->transactions->account\_owner** (nullable, string)  
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.

**report->items->accounts->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->items->accounts->transactions->transaction\_type** (string)  
digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**report->items->accounts->investments** (object)  
A set of fields describing the investments data on an account.

**report->items->accounts->investments->holdings** (\[object\])  
Quantities and values of securities held in the investment account. Map to the securities array for security details.

**report->items->accounts->investments->holdings->account\_id** (string)  
The Plaid account\_id associated with the holding.

**report->items->accounts->investments->holdings->security\_id** (string)  
The Plaid security\_id associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The security\_id for the same security will typically be the same across different institutions, but this is not guaranteed. The security\_id does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**report->items->accounts->investments->holdings->ticker\_symbol** (nullable, string)  
The holding's trading symbol for publicly traded holdings, and otherwise a short identifier if available.

**report->items->accounts->investments->holdings->institution\_price** (number)  
The last price given by the institution for this security. Format: double

**report->items->accounts->investments->holdings->institution\_price\_as\_of** (nullable, string)  
The date at which institution\_price was current. Format: date

**report->items->accounts->investments->holdings->institution\_value** (number)  
The value of the holding, as reported by the institution. Format: double

**report->items->accounts->investments->holdings->cost\_basis** (nullable, number)  
The original total value of the holding. This field is calculated by Plaid as the sum of the purchase price of all of the shares in the holding. Format: double

**report->items->accounts->investments->holdings->quantity** (number)  
The total quantity of the asset held, as reported by the financial institution. If the security is an option, quantity will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: double

**report->items->accounts->investments->holdings->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the holding. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->investments->holdings->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**report->items->accounts->investments->securities** (\[object\])  
Details of specific securities held in on the investment account.

**report->items->accounts->investments->securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**report->items->accounts->investments->securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**report->items->accounts->investments->securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**report->items->accounts->investments->securities->type** (nullable, string)  
The security type of the holding. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**report->items->accounts->investments->transactions** (\[object\])  
Transaction history on the investment account.

**report->items->accounts->investments->transactions->investment\_transaction\_id** (string)  
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment\_transaction\_id is case sensitive.

**report->items->accounts->investments->transactions->account\_id** (string)  
The account\_id of the account against which this transaction posted.

**report->items->accounts->investments->transactions->security\_id** (nullable, string)  
The security\_id to which this transaction is related.

**report->items->accounts->investments->transactions->date** (string)  
The ISO 8601 posting date for the transaction. Format: date

**report->items->accounts->investments->transactions->name** (string)  
The institution’s description of the transaction.

**report->items->accounts->investments->transactions->quantity** (number)  
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: double

**report->items->accounts->investments->transactions->vested\_quantity** (number)  
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities. Format: double

**report->items->accounts->investments->transactions->vested\_value** (number)  
The value of the vested holdings as reported by the institution. Format: double

**report->items->accounts->investments->transactions->amount** (number)  
The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: double

**report->items->accounts->investments->transactions->price** (number)  
The price of the security at which this transaction occurred. Format: double

**report->items->accounts->investments->transactions->fees** (nullable, number)  
The combined value of all fees applied to this transaction Format: double

**report->items->accounts->investments->transactions->type** (string)  
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: buy, sell, cancel, cash, fee, transfer

**report->items->accounts->investments->transactions->subtype** (string)  
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal

**report->items->accounts->investments->transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->investments->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**report->items->accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners.For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning

**report->items->accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**report->items->accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->phone\_numbers->data** (string)  
The phone number.

**report->items->accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**report->items->accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**report->items->accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->emails->data** (string)  
The email address.

**report->items->accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**report->items->accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**report->items->accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**report->items->accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**report->items->accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**report->items->accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**report->items->accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**report->items->accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**report->items->accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**report->items->accounts->ownership\_type** (nullable, string)  
How an asset is owned. association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust. Possible values: null, individual, joint, association, trust

**report->items->accounts->historical\_balances** (\[object\])  
Calculated data about the historical balances on the account.

**report->items->accounts->historical\_balances->date** (string)  
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD) Format: date

**report->items->accounts->historical\_balances->current** (number)  
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction. If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting. Format: double

**report->items->accounts->historical\_balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->historical\_balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**warnings** (\[object\])  
If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing

**warnings->warning\_type** (string)  
The warning type, which will always be ASSET\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. OWNERS\_UNAVAILABLE indicates that account-owner information is not available.INVESTMENTS\_UNAVAILABLE indicates that Investments specific information is not available. TRANSACTIONS\_UNAVAILABLE indicates that transactions information associated with Credit and Depository accounts are unavailable. Possible values: OWNERS\_UNAVAILABLE, INVESTMENTS\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "report": {
    "asset_report_id": "028e8404-a013-4a45-ac9e-002482f9cafc",
    "client_report_id": "client_report_id_1221",
    "date_generated": "2023-03-30T18:27:37Z",
    "days_requested": 90,
    "items": [
      {
        "accounts": [
          {
            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
            "balances": {
              "available": 43200,
              "current": 43200,
              "limit": null,
              "margin_loan_amount": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            },
            "days_available": 90,
            "historical_balances": [
              {
                "current": 49050,
                "date": "2023-03-29",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-27",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-26",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 49050,
                "date": "2023-03-25",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "4444",
            "name": "Plaid Money Market",
            "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "+1 111-555-3333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "+1 111-555-4444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "+1 111-555-5555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "money market",
            "transactions": [
              {
                "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
                "amount": 5850,
                "date": "2023-03-30",
                "iso_currency_code": "USD",
                "original_description": "ACH Electronic CreditGUSTO PAY 123456",
                "pending": false,
                "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
            "balances": {
              "available": 100,
              "current": 110,
              "limit": null,
              "margin_loan_amount": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            },
            "days_available": 90,
            "historical_balances": [
              {
                "current": 110,
                "date": "2023-03-29",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -390,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -373.67,
                "date": "2023-03-27",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -284.27,
                "date": "2023-03-26",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": -284.27,
                "date": "2023-03-25",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "+1 111-555-3333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "+1 111-555-4444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "+1 111-555-5555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "checking",
            "transactions": [
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": 89.4,
                "date": "2023-03-27",
                "iso_currency_code": "USD",
                "original_description": "SparkFun",
                "pending": false,
                "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": 12,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "original_description": "McDonalds #3322",
                "pending": false,
                "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL",
                "unofficial_currency_code": null
              },
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": 4.33,
                "date": "2023-03-28",
                "iso_currency_code": "USD",
                "original_description": "Starbucks",
                "pending": false,
                "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy",
                "unofficial_currency_code": null
              },
              {
                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                "amount": -500,
                "date": "2023-03-29",
                "iso_currency_code": "USD",
                "original_description": "United Airlines **** REFUND ****",
                "pending": false,
                "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2023-03-30T18:25:26Z",
        "institution_id": "ins_109508",
        "institution_name": "First Platypus Bank",
        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7"
      }
    ],
    "user": {
      "client_user_id": "uid_40332",
      "email": "abcharleston@example.com",
      "first_name": "Anna",
      "last_name": "Charleston",
      "middle_name": "B",
      "phone_number": "1-415-867-5309",
      "ssn": "111-22-1234"
    }
  },
  "request_id": "GVzMdiDd8DDAQK4",
  "warnings": []
}
```

\=\*=\*=\*=

#### /credit/relay/refresh 

#### Refresh a report of a relay token 

The [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) endpoint allows third parties to refresh a report that was relayed to them, using a `relay_token` that was created by the report owner. A new report will be created with the original report parameters, but with the most recent data available based on the `days_requested` value of the original report.

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

**relay\_token** (required, string)  
The relay\_token granting access to the report you would like to refresh.

**report\_type** (required, string)  
The report type. It can be asset. Income report types are not yet supported. Possible values: asset

**webhook** (string)  
The URL registered to receive webhooks when the report of a relay token has been refreshed.

```javascript
const request: CreditRelayRefreshRequest = {
  relay_token: createResponse.data.relay_token,
  report_type: 'assets',
};
try {
  const response = await plaidClient.CreditRelayRefresh(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**asset\_report\_id** (string)  
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "relay_token": "credit-relay-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq",
  "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d"
}
```

\=\*=\*=\*=

#### /credit/relay/remove 

#### Remove relay token 

The [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) endpoint allows you to invalidate a `relay_token`. The third party holding the token will no longer be able to access or refresh the reports which the `relay_token` gives access to. The original report, associated Items, and other relay tokens that provide access to the same report are not affected and will remain accessible after removing the given `relay_token`.

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

**relay\_token** (required, string)  
The relay\_token you would like to revoke.

```javascript
const request: CreditRelayRemoveRequest = {
  relay_token: createResponse.data.relay_token,
};
try {
  const response = await plaidClient.creditRelayRemove(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**removed** (boolean)  
true if the relay token was successfully removed.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "removed": true,
  "request_id": "m8MDnv9okwxFNBV"
}
```

### Webhooks 

\=\*=\*=\*=

#### PRODUCT\_READY 

Fired when the Asset Report has been generated and [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) is ready to be called. If you attempt to retrieve an Asset Report before this webhook has fired, you’ll receive a response with the HTTP status code 400 and a Plaid error code of `PRODUCT_NOT_READY`.

#### Properties 

**webhook\_type** (string)  
ASSETS

**webhook\_code** (string)  
PRODUCT\_READY

**asset\_report\_id** (string)  
The asset\_report\_id corresponding to the Asset Report the webhook has fired for.

**user\_id** (string)  
The user\_id corresponding to the User ID the webhook has fired for.

**report\_type** (string)  
Indicates either a Fast Asset Report, which will contain only current identity and balance information, or a Full Asset Report, which will also contain historical balance information and transaction data. Possible values: FULL, FAST

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ASSETS",
  "webhook_code": "PRODUCT_READY",
  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
  "report_type": "FULL"
}
```

\=\*=\*=\*=

#### ERROR 

Fired when Asset Report generation has failed. The resulting `error` will have an `error_type` of `ASSET_REPORT_ERROR`.

#### Properties 

**webhook\_type** (string)  
ASSETS

**webhook\_code** (string)  
ERROR

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**asset\_report\_id** (string)  
The ID associated with the Asset Report.

**user\_id** (string)  
The user\_id corresponding to the User ID the webhook has fired for.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ASSETS",
  "webhook_code": "ERROR",
  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
  "error": {
    "display_message": null,
    "error_code": "PRODUCT_NOT_ENABLED",
    "error_message": "the 'assets' product is not enabled for the following access tokens: access-sandbox-fb88b20c-7b74-4197-8d01-0ab122dad0bc. please ensure that 'assets' is included in the 'product' array when initializing Link and create the Item(s) again.",
    "error_type": "ASSET_REPORT_ERROR",
    "request_id": "m8MDnv9okwxFNBV"
  }
}
```

---


# API - Auth | Plaid Docs

Auth 
=====

#### API reference for Auth endpoints and webhooks 

Retrieve bank account information to set up electronic funds transfers, such as ACH payments in the US, EFT payments in Canada, BACS payments in the UK, and IBAN / SIC payments in the EU.

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

| Endpoints |  |
| --- | --- |
| [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) | Fetch account information |
| [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) | Search for updates on micro-deposit verification statuses based on filter criteria |
| [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) | Get updates on micro-deposit verification statuses using a cursor |

| See also |  |
| --- | --- |
| [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | Create a token for using Auth with a processing partner |
| [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | Create a token for testing Auth with a processing partner |
| [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) | Create a token for using Auth with Stripe as a processing partner |
| [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | Change a Sandbox Item's micro-deposit verification status |

| Webhooks |  |
| --- | --- |
| [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#default_update) | Item has account(s) with updated Auth data |
| [AUTOMATICALLY\_VERIFIED](https://plaid.com/docs/api/products/auth/index.html.md#automatically_verified) | Item has been verified |
| [VERIFICATION\_EXPIRED](https://plaid.com/docs/api/products/auth/index.html.md#verification_expired) | Item verification has failed |
| [BANK\_TRANSFERS\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfers_events_update) | New micro-deposit verification events available |
| [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) | Text message verification status has changed |

### Endpoints 

\=\*=\*=\*=

#### /auth/get 

#### Retrieve auth data 

The [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint returns the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's checking, savings, and cash management accounts, along with high-level account data and balances when available.  
Versioning note: In API version 2017-03-08, the schema of the `numbers` object returned by this endpoint is substantially different. For details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2018-05-22) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /auth/get results.

**options->account\_ids** (\[string\])  
A list of account\_ids to retrieve for the Item. Note: An error will be returned if a provided account\_id is not associated with the Item.

```javascript
const request: AuthGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.authGet(request);
  const accountData = response.data.accounts;
  const numbers = response.data.numbers;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
The accounts for which numbers are being retrieved.

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**numbers** (object)  
An object containing identifying numbers used for making electronic transfers to and from the accounts. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by any accounts for which data has been requested, the array for that type will be empty.

**numbers->ach** (\[object\])  
An array of ACH numbers identifying accounts.

**numbers->ach->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->ach->account** (string)  
The ACH account number for the account. At certain institutions, including Chase, PNC, and (coming May 2025) US Bank, you will receive "tokenized" routing and account numbers, which are not the user's actual account and routing numbers. For important details on how this may impact your integration and on how to avoid fraud, user confusion, and ACH returns, see Tokenized account numbers.

**numbers->ach->is\_tokenized\_account\_number** (boolean)  
Indicates whether the account number is tokenized by the institution. For important details on how tokenized account numbers may impact your integration, see Tokenized account numbers.

**numbers->ach->routing** (string)  
The ACH routing number for the account. This may be a tokenized routing number. For more information, see Tokenized account numbers.

**numbers->ach->wire\_routing** (nullable, string)  
The wire transfer routing number for the account. This field is only populated if the institution is known to use a separate wire transfer routing number. Many institutions do not have a separate wire routing number and use the ACH routing number for wires instead. It is recommended to have the end user manually confirm their wire routing number before sending any wires to their account, especially if this field is null.

**numbers->eft** (\[object\])  
An array of EFT numbers identifying accounts.

**numbers->eft->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->eft->account** (string)  
The EFT account number for the account

**numbers->eft->institution** (string)  
The EFT institution number for the account

**numbers->eft->branch** (string)  
The EFT branch number for the account

**numbers->international** (\[object\])  
An array of IBAN numbers identifying accounts.

**numbers->international->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->international->iban** (string)  
The International Bank Account Number (IBAN) for the account

**numbers->international->bic** (string)  
The Bank Identifier Code (BIC) for the account

**numbers->bacs** (\[object\])  
An array of BACS numbers identifying accounts.

**numbers->bacs->account\_id** (string)  
The Plaid account ID associated with the account numbers

**numbers->bacs->account** (string)  
The BACS account number for the account

**numbers->bacs->sort\_code** (string)  
The BACS sort code for the account

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": {
        "available": 100,
        "current": 110,
        "limit": null,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "mask": "9606",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "numbers": {
    "ach": [
      {
        "account": "9900009606",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "routing": "011401533",
        "wire_routing": "021000021",
        "is_tokenized_account_number": false
      }
    ],
    "eft": [
      {
        "account": "111122223333",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "institution": "021",
        "branch": "01140"
      }
    ],
    "international": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "bic": "NWBKGB21",
        "iban": "GB29NWBK60161331926819"
      }
    ],
    "bacs": [
      {
        "account": "31926819",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "sort_code": "601613"
      }
    ]
  },
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": [
      "assets",
      "auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "institution_name": "Royal Bank of Plaid",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "m8MDnv9okwxFNBV"
}
```

\=\*=\*=\*=

#### /bank\_transfer/event/list 

#### List bank transfer events 

Use the [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) endpoint to get a list of Plaid-initiated ACH or bank transfer events based on specified filter criteria. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) .

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

**start\_date** (string)  
The start datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**end\_date** (string)  
The end datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**bank\_transfer\_id** (string)  
Plaid’s unique identifier for a bank transfer.

**account\_id** (string)  
The account ID to get events for all transactions to/from an account.

**bank\_transfer\_type** (string)  
The type of bank transfer. This will be either debit or credit. A debit indicates a transfer of money into your origination account; a credit indicates a transfer of money out of your origination account. Possible values: debit, credit, null

**event\_types** (\[string\])  
Filter events by event type. Possible values: pending, cancelled, failed, posted, reversed

**count** (integer)  
The maximum number of bank transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned. Default: 25 Maximum: 25 Minimum: 1

**offset** (integer)  
The offset into the list of bank transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 bank transfer events will be returned. Default: 0 Minimum: 0

**origination\_account\_id** (string)  
The origination account ID to get events for transfers from a specific origination account.

**direction** (string)  
Indicates the direction of the transfer: outbound: for API-initiated transfers inbound: for payments received by the FBO account. Possible values: inbound, outbound, null

```javascript
const request: BankTransferEventListRequest = {
  start_date: start_date,
  end_date: end_date,
  bank_transfer_id: bank_transfer_id,
  account_id: account_id,
  bank_transfer_type: bank_transfer_type,
  event_types: event_types,
  count: count,
  offset: offset,
  origination_account_id: origination_account_id,
  direction: direction,
};
try {
  const response = await plaidClient.bankTransferEventList(request);
  const events = response.data.bank_transfer_events;
  for (const event of events) {
    // iterate through events
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

integer

**bank\_transfer\_events** (\[object\])  
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: 0

**bank\_transfer\_events->timestamp** (string)  
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**bank\_transfer\_events->event\_type** (string)  
The type of event that this bank transfer represents. pending: A new transfer was created; it is in the pending state. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. posted: The transfer has been successfully submitted to the payment network. reversed: A posted transfer was reversed. Possible values: pending, cancelled, failed, posted, reversed

**bank\_transfer\_events->account\_id** (string)  
The account ID associated with the bank transfer.

**bank\_transfer\_events->bank\_transfer\_id** (string)  
Plaid’s unique identifier for a bank transfer.

**bank\_transfer\_events->origination\_account\_id** (nullable, string)  
The ID of the origination account that this balance belongs to.

**bank\_transfer\_events->bank\_transfer\_type** (string)  
The type of bank transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**bank\_transfer\_events->bank\_transfer\_amount** (string)  
The bank transfer amount.

**bank\_transfer\_events->bank\_transfer\_iso\_currency\_code** (string)  
The currency of the bank transfer amount.

**bank\_transfer\_events->failure\_reason** (nullable, object)  
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.

**bank\_transfer\_events->failure\_reason->ach\_return\_code** (nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Bank Transfers errors.

**bank\_transfer\_events->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**bank\_transfer\_events->direction** (nullable, string)  
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account. Possible values: outbound, inbound, null

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "bank_transfer_events": [
    {
      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
      "bank_transfer_amount": "12.34",
      "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "bank_transfer_iso_currency_code": "USD",
      "bank_transfer_type": "credit",
      "direction": "outbound",
      "event_id": 1,
      "event_type": "pending",
      "failure_reason": null,
      "origination_account_id": "",
      "timestamp": "2020-08-06T17:27:15Z"
    }
  ],
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /bank\_transfer/event/sync 

#### Sync bank transfer events 

[/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) allows you to request up to the next 25 Plaid-initiated bank transfer events that happened after a specific `event_id`. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) .

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

**after\_id** (required, integer)  
The latest (largest) event\_id fetched via the sync endpoint, or 0 initially. Minimum: 0

**count** (integer)  
The maximum number of bank transfer events to return. Default: 25 Minimum: 1 Maximum: 25

```javascript
const request: BankTransferEventListRequest = {
  after_id: afterID,
  count: 25,
};
try {
  const response = await plaidClient.bankTransferEventSync(request);
  const events = response.data.bank_transfer_events;
  for (const event of events) {
    // iterate through events
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

integer

**bank\_transfer\_events** (\[object\])  
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: 0

**bank\_transfer\_events->timestamp** (string)  
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**bank\_transfer\_events->event\_type** (string)  
The type of event that this bank transfer represents. pending: A new transfer was created; it is in the pending state. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. posted: The transfer has been successfully submitted to the payment network. reversed: A posted transfer was reversed. Possible values: pending, cancelled, failed, posted, reversed

**bank\_transfer\_events->account\_id** (string)  
The account ID associated with the bank transfer.

**bank\_transfer\_events->bank\_transfer\_id** (string)  
Plaid’s unique identifier for a bank transfer.

**bank\_transfer\_events->origination\_account\_id** (nullable, string)  
The ID of the origination account that this balance belongs to.

**bank\_transfer\_events->bank\_transfer\_type** (string)  
The type of bank transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**bank\_transfer\_events->bank\_transfer\_amount** (string)  
The bank transfer amount.

**bank\_transfer\_events->bank\_transfer\_iso\_currency\_code** (string)  
The currency of the bank transfer amount.

**bank\_transfer\_events->failure\_reason** (nullable, object)  
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.

**bank\_transfer\_events->failure\_reason->ach\_return\_code** (nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Bank Transfers errors.

**bank\_transfer\_events->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**bank\_transfer\_events->direction** (nullable, string)  
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account. Possible values: outbound, inbound, null

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "bank_transfer_events": [
    {
      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
      "bank_transfer_amount": "12.34",
      "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "bank_transfer_iso_currency_code": "USD",
      "bank_transfer_type": "credit",
      "direction": "outbound",
      "event_id": 1,
      "event_type": "pending",
      "failure_reason": null,
      "origination_account_id": "",
      "timestamp": "2020-08-06T17:27:15Z"
    }
  ],
  "request_id": "mdqfuVxeoza6mhu"
}
```

### Webhooks 

Updates are sent for Items that are linked using micro-deposits (excluding Instant Micro-deposits).

When an automated micro-deposit is created, Plaid sends a webhook upon successful verification. If verification does not succeed after seven days for an automated micro-deposit, Plaid sends a `VERIFICATION_EXPIRED` webhook. If you attempt to retrieve an automated micro-deposit Item before verification succeeds, you’ll receive a response with the HTTP status code 400 and a Plaid error code of `PRODUCT_NOT_READY`. For Same-Day micro-deposits, Plaid does not send `AUTOMATICALLY_VERIFIED` or `VERIFICATION_EXPIRED` webhooks, but you may instead use the `BANK_TRANSFERS_EVENTS_UPDATE` webhook to [access the underlying ACH events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) of micro-deposits.

Plaid will trigger a `DEFAULT_UPDATE` webhook for Items that undergo a change in Auth data. This is generally caused by data partners notifying Plaid of a change in their account numbering system or to their routing numbers. To avoid returned transactions, customers that receive a `DEFAULT_UPDATE` webhook with the `account_ids_with_updated_auth` object populated should immediately discontinue all usages of existing Auth data for those accounts and call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) to obtain updated account and routing numbers.

\=\*=\*=\*=

#### DEFAULT\_UPDATE 

Plaid will trigger a `DEFAULT_UPDATE` webhook for Items that undergo a change in Auth data. This is generally caused by data partners notifying Plaid of a change in their account numbering system or to their routing numbers. To avoid returned transactions, customers that receive a `DEFAULT_UPDATE` webhook with the `account_ids_with_updated_auth` object populated should immediately discontinue all usages of existing Auth data for those accounts and call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) to obtain updated account and routing numbers.

#### Properties 

**webhook\_type** (string)  
AUTH

**webhook\_code** (string)  
DEFAULT\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**account\_ids\_with\_new\_auth** (\[string\])  
An array of account\_id's for accounts that contain new auth.

**account\_ids\_with\_updated\_auth** (object)  
An object with keys of account\_id's that are mapped to their respective auth attributes that changed. ACCOUNT\_NUMBER and ROUTING\_NUMBER are the two potential values that can be flagged as updated. Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": \["ACCOUNT\_NUMBER"\] }

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "AUTH",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "account_ids_with_updated_auth": {
    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp": [
      "ACCOUNT_NUMBER"
    ]
  },
  "error": null,
  "environment": "production"
}
```

\=\*=\*=\*=

#### AUTOMATICALLY\_VERIFIED 

Fired when an Item is verified via automated micro-deposits. We recommend communicating to your users when this event is received to notify them that their account is verified and ready for use.

#### Properties 

**webhook\_type** (string)  
AUTH

**webhook\_code** (string)  
AUTOMATICALLY\_VERIFIED

**account\_id** (string)  
The account\_id of the account associated with the webhook

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

```json
{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
  "environment": "production",
  "error": null
}
```

\=\*=\*=\*=

#### VERIFICATION\_EXPIRED 

Fired when an Item was not verified via automated micro-deposits after seven days since the automated micro-deposit was made.

#### Properties 

**webhook\_type** (string)  
AUTH

**webhook\_code** (string)  
VERIFICATION\_EXPIRED

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**account\_id** (string)  
The account\_id of the account associated with the webhook

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

```json
{
  "webhook_type": "AUTH",
  "webhook_code": "VERIFICATION_EXPIRED",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
  "environment": "production",
  "error": null
}
```

\=\*=\*=\*=

#### BANK\_TRANSFERS\_EVENTS\_UPDATE 

Fired when new ACH events are available. To begin receiving this webhook, you must first register your webhook listener endpoint via the [webhooks page in the Dashboard](https://dashboard.plaid.com/team/webhooks) . The `BANK_TRANSFERS_EVENTS_UPDATE` webhook can be used to track the progress of ACH transfers used in [micro-deposit verification](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) . Receiving this webhook indicates you should fetch the new events from [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) . Note that [Transfer](https://plaid.com/docs/transfer/index.html.md) customers should use Transfer webhooks instead of using `BANK_TRANSFERS_EVENTS_UPDATE`; see [micro-deposit events documentation](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) for more details.

#### Properties 

**webhook\_type** (string)  
BANK\_TRANSFERS

**webhook\_code** (string)  
BANK\_TRANSFERS\_EVENTS\_UPDATE

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "BANK_TRANSFERS",
  "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE",
  "environment": "production"
}
```

\=\*=\*=\*=

#### SMS\_MICRODEPOSITS\_VERIFICATION 

Contains the state of a SMS same-day microdeposits verification session.

#### Properties 

**webhook\_type** (string)  
AUTH

**webhook\_code** (string)  
SMS\_MICRODEPOSITS\_VERIFICATION

**status** (string)  
The final status of the same-day microdeposits verification. Will always be MANUALLY\_VERIFIED or VERIFICATION\_FAILED.

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**account\_id** (string)  
The external account ID of the affected account

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "AUTH",
  "webhook_code": "SMS_MICRODEPOSITS_VERIFICATION",
  "status": "MANUALLY_VERIFIED",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
  "environment": "sandbox"
}
```

---


# API - Balance | Plaid Docs

Balance 
========

#### API reference for Balance endpoints and webhooks 

Verify real-time account balances. For how-to guidance, see the [Balance documentation](https://plaid.com/docs/balance/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) | Fetch real-time account balances |

### Endpoints 

\=\*=\*=\*=

#### /accounts/balance/get 

#### Retrieve real-time balance data 

The [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) endpoint returns the real-time balance for each of an Item's accounts. While other endpoints, such as [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) , return a balance object, only [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) forces the available and current balance fields to be refreshed rather than cached. This endpoint can be used for existing Items that were added via any of Plaid’s other products. This endpoint can be used as long as Link has been initialized with any other product, `balance` itself is not a product that can be used to initialize Link. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests.

#### Request fields and example 

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

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

**options** (object)  
Optional parameters to /accounts/balance/get.

**options->account\_ids** (\[string\])  
A list of account\_ids to retrieve for the Item. The default value is null. Note: An error will be returned if a provided account\_id is not associated with the Item.

**options->min\_last\_updated\_datetime** (string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get. This field is only necessary when the institution is ins\_128026 (Capital One), and one or more account types being requested is a non-depository account (such as a credit card) as Capital One does not provide real-time balance for non-depository accounts. In this case, a value must be provided or an INVALID\_REQUEST error with the code of INVALID\_FIELD will be returned. For all other institutions, as well as for depository accounts at Capital One (including all checking and savings accounts) this field is ignored and real-time balance information will be fetched. If this field is not ignored, and no acceptable balance is available, an INVALID\_RESULT error with the code LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE will be returned. Format: date-time

```javascript
// Pull real-time balance information for each account associated
// with the Item
const request: AccountsGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.accountsBalanceGet(request);
  const accounts = response.data.accounts;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
An array of financial institution accounts associated with the Item. If /accounts/balance/get was called, each account will include real-time balance information.

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "holder_category": "personal",
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "balances": {
        "available": null,
        "current": 410,
        "iso_currency_code": "USD",
        "limit": 2000,
        "unofficial_currency_code": null
      },
      "mask": "3333",
      "name": "Plaid Credit Card",
      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
      "subtype": "credit card",
      "type": "credit"
    },
    {
      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "identity",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "institution_name": "Chase",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "qk5Bxes3gDfv4F2"
}
```

---


# API - Beacon (beta) | Plaid Docs

Beacon 
=======

#### API reference for Beacon endpoints and webhooks 

Add and report users on the Plaid Beacon network.

| Endpoints |  |
| --- | --- |
| [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) | Create and scan a Beacon User against a Beacon Program |
| [/beacon/user/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserget) | Fetch a Beacon User |
| [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) | Update and rescan a Beacon User |
| [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) | Fetch a Beacon User's account insights |
| [/beacon/user/history/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserhistorylist) | List a Beacon User's history |
| [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) | Create a fraud report for a given Beacon User |
| [/beacon/report/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportget) | Fetch a Beacon Report |
| [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) | List Beacon Reports for a given Beacon User |
| [/beacon/report\_syndication/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationget) | Fetch a Beacon Report Syndication |
| [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) | List Beacon Report Syndications for a given Beacon User |
| [/beacon/duplicate/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconduplicateget) | Fetch a Beacon duplicate |

| See also |  |
| --- | --- |
| [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user |
| [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users |

| Webhooks |  |
| --- | --- |
| [USER\_STATUS\_UPDATED](https://plaid.com/docs/api/products/beacon/index.html.md#user_status_updated) | Beacon User status has changed |
| [REPORT\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_created) | Beacon Report has been created |
| [REPORT\_UPDATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_updated) | Beacon Report has been updated |
| [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) | New Network Report matches one of your Users |
| [DUPLICATE\_DETECTED](https://plaid.com/docs/api/products/beacon/index.html.md#duplicate_detected) | Duplicate Beacon User was created |

\=\*=\*=\*=

#### /beacon/user/create 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Create a Beacon User 

Create and scan a Beacon User against your Beacon Program, according to your program's settings.  
When you submit a new user to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , several checks are performed immediately:  
\- The user's PII (provided within the `user` object) is searched against all other users within the Beacon Program you specified. If a match is found that violates your program's "Duplicate Information Filtering" settings, the user will be returned with a status of `pending_review`.  
\- The user's PII is also searched against all fraud reports created by your organization across all of your Beacon Programs. If the user's data matches a fraud report that your team created, the user will be returned with a status of `rejected`.  
\- Finally, the user's PII is searched against all fraud report shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a `pending_review` status if your program has enabled automatic flagging based on network fraud.

#### Request fields 

**program\_id** (required, string)  
ID of the associated Beacon Program.

**client\_user\_id** (required, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**user** (required, object)  
A Beacon User's data which is used to check against duplicate records and the Beacon Fraud Network. In order to create a Beacon User, in addition to the name, either the date\_of\_birth or the depository\_accounts field must be provided.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (required, object)  
The full name for a given Beacon User.

**user->name->given\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Home address for the associated user. For more context on this field, see Input Validation by Country.

**user->address->street** (required, string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (required, string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (required, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (string)  
A phone number in E.164 format.

**user->id\_number** (object)  
The ID number associated with a Beacon User.

**user->id\_number->value** (required, string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (required, string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**user->ip\_address** (string)  
An IPv4 or IPV6 address.

**user->depository\_accounts** (\[object\])  
Provide a list of bank accounts that are associated with this Beacon User. These accounts will be scanned across the Beacon Network and used to find duplicate records. Note: These accounts will not have Bank Account Insights. To receive Bank Account Insights please supply access\_tokens.

**user->depository\_accounts->account\_number** (required, string)  
Must be a valid US Bank Account Number

**user->depository\_accounts->routing\_number** (required, string)  
The routing number of the account.

**access\_tokens** (\[string\])  
Send this array of access tokens to link accounts to the Beacon User and have them evaluated for Account Insights. A maximum of 50 accounts total can be added to a single Beacon User.

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

```javascript
const request: BeaconUserCreateRequest = {
  program_id: 'becprg_11111111111111',
  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
  access_tokens: [access_token],
  user: {
    email_address: 'user@example.com',
    date_of_birth: '1975-01-18',
    name: {
      given_name: 'Leslie',
      family_name: 'Knope',
    },
    address: {
      street: '123 Main St.',
      street2: 'Unit 42',
      city: 'Pawnee',
      region: 'IN',
      postal_code: '46001',
      country: 'US',
    },
  },
};


try {
  const response = await plaidClient.beaconUserCreate(request);
  console.log(response.status.value);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**item\_ids** (\[string\])  
An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

**id** (string)  
ID of the associated Beacon User.

**version** (integer)  
The version field begins with 1 and increments each time the user is updated.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**updated\_at** (string)  
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: date-time

**status** (string)  
A status of a Beacon User. rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. pending\_review: The Beacon User has been marked for review. cleared: The Beacon User has been cleared of fraud. Possible values: rejected, pending\_review, cleared

**program\_id** (string)  
ID of the associated Beacon Program.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**user** (object)  
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (object)  
The full name for a given Beacon User.

**user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code

**user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (nullable, string)  
A phone number in E.164 format.

**user->id\_number** (nullable, object)  
The ID number associated with a Beacon User.

**user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

string

**user->depository\_accounts** (\[object\])  
The last 2-4 numeric characters of this account’s account number.

**user->depository\_accounts->routing\_number** (string)  
The routing number of the account.

**user->depository\_accounts->added\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "item_ids": [
    "515cd85321d3649aecddc015"
  ],
  "id": "becusr_42cF1MNo42r9Xj",
  "version": 1,
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "status": "cleared",
  "program_id": "becprg_11111111111111",
  "client_user_id": "your-db-id-3b24110",
  "user": {
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "email_address": "user@example.com",
    "phone_number": "+19876543212",
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    },
    "ip_address": "192.0.2.42",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "added_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/get 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get a Beacon User 

Fetch a Beacon User.  
The Beacon User is returned with all of their associated information and a `status` based on the Beacon Network duplicate record and fraud checks.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

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

```javascript
const request: BeaconUserGetRequest = {
  beacon_user_id: 'becusr_11111111111111',
};


try {
  const response = await plaidClient.beaconUserGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**item\_ids** (\[string\])  
An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

**id** (string)  
ID of the associated Beacon User.

**version** (integer)  
The version field begins with 1 and increments each time the user is updated.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**updated\_at** (string)  
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: date-time

**status** (string)  
A status of a Beacon User. rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. pending\_review: The Beacon User has been marked for review. cleared: The Beacon User has been cleared of fraud. Possible values: rejected, pending\_review, cleared

**program\_id** (string)  
ID of the associated Beacon Program.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**user** (object)  
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (object)  
The full name for a given Beacon User.

**user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code

**user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (nullable, string)  
A phone number in E.164 format.

**user->id\_number** (nullable, object)  
The ID number associated with a Beacon User.

**user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

string

**user->depository\_accounts** (\[object\])  
The last 2-4 numeric characters of this account’s account number.

**user->depository\_accounts->routing\_number** (string)  
The routing number of the account.

**user->depository\_accounts->added\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "item_ids": [
    "515cd85321d3649aecddc015"
  ],
  "id": "becusr_42cF1MNo42r9Xj",
  "version": 1,
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "status": "cleared",
  "program_id": "becprg_11111111111111",
  "client_user_id": "your-db-id-3b24110",
  "user": {
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "email_address": "user@example.com",
    "phone_number": "+19876543212",
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    },
    "ip_address": "192.0.2.42",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "added_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/update 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Update the identity data of a Beacon User 

Update the identity data for a Beacon User in your Beacon Program or add new accounts to the Beacon User.  
Similar to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , several checks are performed immediately when you submit an identity data change to [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) :  
\- The user's updated PII is searched against all other users within the Beacon Program you specified. If a match is found that violates your program's "Duplicate Information Filtering" settings, the user will be returned with a status of `pending_review`.  
\- The user's updated PII is also searched against all fraud reports created by your organization across all of your Beacon Programs. If the user's data matches a fraud report that your team created, the user will be returned with a status of `rejected`.  
\- Finally, the user's PII is searched against all fraud report shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a `pending_review` status if your program has enabled automatic flagging based on network fraud.  
Plaid maintains a version history for each Beacon User, so the Beacon User's identity data before and after the update is retained as separate versions.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

**user** (object)  
A subset of a Beacon User's data which is used to patch the existing identity data associated with a Beacon User. At least one field must be provided. If left unset or null, user data will not be patched.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (object)  
The full name for a given Beacon User.

**user->name->given\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Home address for the associated user. For more context on this field, see Input Validation by Country.

**user->address->street** (required, string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (required, string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (required, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (string)  
A phone number in E.164 format.

**user->id\_number** (object)  
The ID number associated with a Beacon User.

**user->id\_number->value** (required, string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (required, string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**user->ip\_address** (string)  
An IPv4 or IPV6 address.

required, string

**user->depository\_accounts** (\[object\])  
Must be a valid US Bank Account Number

**user->depository\_accounts->routing\_number** (required, string)  
The routing number of the account.

**access\_tokens** (\[string\])  
Send this array of access tokens to add accounts to this user for evaluation. This will add accounts to this Beacon User. If left null only existing accounts will be returned in response. A maximum of 50 accounts total can be added to a Beacon User.

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

```javascript
const request: BeaconUserUpdateRequest = {
  beacon_user_id: 'becusr_11111111111111',
  user: {
    email_address: 'user@example.com',
    date_of_birth: '1975-01-18',
    name: {
      given_name: 'Leslie',
      family_name: 'Knope',
    },
    address: {
      street: '123 Main St.',
      street2: 'Unit 42',
      city: 'Pawnee',
      region: 'IN',
      postal_code: '46001',
      country: 'US',
    },
  },
};


try {
  const response = await plaidClient.beaconUserUpdate(request);
  console.log(response.status.value);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**item\_ids** (\[string\])  
An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

**id** (string)  
ID of the associated Beacon User.

**version** (integer)  
The version field begins with 1 and increments each time the user is updated.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**updated\_at** (string)  
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: date-time

**status** (string)  
A status of a Beacon User. rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. pending\_review: The Beacon User has been marked for review. cleared: The Beacon User has been cleared of fraud. Possible values: rejected, pending\_review, cleared

**program\_id** (string)  
ID of the associated Beacon Program.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**user** (object)  
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (object)  
The full name for a given Beacon User.

**user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code

**user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (nullable, string)  
A phone number in E.164 format.

**user->id\_number** (nullable, object)  
The ID number associated with a Beacon User.

**user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

string

**user->depository\_accounts** (\[object\])  
The last 2-4 numeric characters of this account’s account number.

**user->depository\_accounts->routing\_number** (string)  
The routing number of the account.

**user->depository\_accounts->added\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "item_ids": [
    "515cd85321d3649aecddc015"
  ],
  "id": "becusr_42cF1MNo42r9Xj",
  "version": 1,
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "status": "cleared",
  "program_id": "becprg_11111111111111",
  "client_user_id": "your-db-id-3b24110",
  "user": {
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "email_address": "user@example.com",
    "phone_number": "+19876543212",
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    },
    "ip_address": "192.0.2.42",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "added_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/account\_insights/get 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get Account Insights for a Beacon User 

Get Account Insights for all Accounts linked to this Beacon User. The insights for each account are computed based on the information that was last retrieved from the financial institution.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

```javascript
const request: BeaconUserAccountInsightsGetRequest = {
  beacon_user_id: 'becusr_11111111111111',
  access_token: 'access-sandbox-12345678',
  client_id: process.env.PLAID_CLIENT_ID,
  secret: process.env.PLAID_SECRET,
};


try {
  const response = await plaidClient.beaconUserAccountInsightsGet(request);
  console.log(response.status.value);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**beacon\_user\_id** (string)  
ID of the associated Beacon User.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**updated\_at** (string)  
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: date-time

**bank\_account\_insights** (object)  
A collection of Bank Accounts linked to an Item that is associated with this Beacon User.

**bank\_account\_insights->item\_id** (string)  
The Plaid Item ID the Bank Accounts belong to.

string

**bank\_account\_insights->accounts** (\[object\])  
The Plaid account\_id

**bank\_account\_insights->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**bank\_account\_insights->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**bank\_account\_insights->accounts->attributes** (object)  
The attributes object contains data that can be used to assess account risk. Examples of data include: days\_since\_first\_plaid\_connection: The number of days since the first time the Item was connected to an application via Plaid plaid\_connections\_count\_7d: The number of times the Item has been connected to applications via Plaid over the past 7 days plaid\_connections\_count\_30d: The number of times the Item has been connected to applications via Plaid over the past 30 days total\_plaid\_connections\_count: The number of times the Item has been connected to applications via Plaid For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager

**bank\_account\_insights->accounts->attributes->days\_since\_first\_plaid\_connection** (nullable, integer)  
The number of days since the first time the Item was connected to an application via Plaid

**bank\_account\_insights->accounts->attributes->is\_account\_closed** (nullable, boolean)  
Indicates if the account has been closed by the financial institution or the consumer, or is at risk of being closed

**bank\_account\_insights->accounts->attributes->is\_account\_frozen\_or\_restricted** (nullable, boolean)  
Indicates whether the account has withdrawals and transfers disabled or if access to the account is restricted. This could be due to a freeze by the credit issuer, legal restrictions (e.g., sanctions), or regulatory requirements limiting monthly withdrawals, among other reasons

**bank\_account\_insights->accounts->attributes->total\_plaid\_connections\_count** (nullable, integer)  
The total number of times the item has been connected to applications via Plaid

**bank\_account\_insights->accounts->attributes->plaid\_connections\_count\_7d** (nullable, integer)  
The number of times the Item has been connected to applications via Plaid over the past 7 days

**bank\_account\_insights->accounts->attributes->plaid\_connections\_count\_30d** (nullable, integer)  
The number of times the Item has been connected to applications via Plaid over the past 30 days

**bank\_account\_insights->accounts->attributes->failed\_plaid\_non\_oauth\_authentication\_attempts\_count\_3d** (nullable, integer)  
The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 3 days

**bank\_account\_insights->accounts->attributes->plaid\_non\_oauth\_authentication\_attempts\_count\_3d** (nullable, integer)  
The number of non-OAuth authentication attempts via Plaid for this bank account over the past 3 days

**bank\_account\_insights->accounts->attributes->failed\_plaid\_non\_oauth\_authentication\_attempts\_count\_7d** (nullable, integer)  
The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 7 days

**bank\_account\_insights->accounts->attributes->plaid\_non\_oauth\_authentication\_attempts\_count\_7d** (nullable, integer)  
The number of non-OAuth authentication attempts via Plaid for this bank account over the past 7 days

**bank\_account\_insights->accounts->attributes->failed\_plaid\_non\_oauth\_authentication\_attempts\_count\_30d** (nullable, integer)  
The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 30 days

**bank\_account\_insights->accounts->attributes->plaid\_non\_oauth\_authentication\_attempts\_count\_30d** (nullable, integer)  
The number of non-OAuth authentication attempts via Plaid for this bank account over the past 30 days

**bank\_account\_insights->accounts->attributes->distinct\_ip\_addresses\_count\_3d** (nullable, integer)  
The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 3 days

**bank\_account\_insights->accounts->attributes->distinct\_ip\_addresses\_count\_7d** (nullable, integer)  
The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 7 days

**bank\_account\_insights->accounts->attributes->distinct\_ip\_addresses\_count\_30d** (nullable, integer)  
The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 30 days

**bank\_account\_insights->accounts->attributes->distinct\_ip\_addresses\_count\_90d** (nullable, integer)  
The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 90 days

**bank\_account\_insights->accounts->attributes->distinct\_user\_agents\_count\_3d** (nullable, integer)  
The number of distinct user agents linked to the same bank account during Plaid authentication in the last 3 days

**bank\_account\_insights->accounts->attributes->distinct\_user\_agents\_count\_7d** (nullable, integer)  
The number of distinct user agents linked to the same bank account during Plaid authentication in the last 7 days

**bank\_account\_insights->accounts->attributes->distinct\_user\_agents\_count\_30d** (nullable, integer)  
The number of distinct user agents linked to the same bank account during Plaid authentication in the last 30 days

**bank\_account\_insights->accounts->attributes->distinct\_user\_agents\_count\_90d** (nullable, integer)  
The number of distinct user agents linked to the same bank account during Plaid authentication in the last 90 days

**bank\_account\_insights->accounts->attributes->address\_change\_count\_28d** (nullable, integer)  
The number of times the account's addresses on file have changed over the past 28 days

**bank\_account\_insights->accounts->attributes->email\_change\_count\_28d** (nullable, integer)  
The number of times the account's email addresses on file have changed over the past 28 days

**bank\_account\_insights->accounts->attributes->phone\_change\_count\_28d** (nullable, integer)  
The number of times the account's phone numbers on file have changed over the past 28 days

**bank\_account\_insights->accounts->attributes->address\_change\_count\_90d** (nullable, integer)  
The number of times the account's addresses on file have changed over the past 90 days

**bank\_account\_insights->accounts->attributes->email\_change\_count\_90d** (nullable, integer)  
The number of times the account's email addresses on file have changed over the past 90 days

**bank\_account\_insights->accounts->attributes->phone\_change\_count\_90d** (nullable, integer)  
The number of times the account's phone numbers on file have changed over the past 90 days

**bank\_account\_insights->accounts->attributes->days\_since\_account\_opening** (nullable, integer)  
The number of days since the bank account was opened, as reported by the financial institution

**bank\_account\_insights->accounts->attributes->days\_since\_first\_observed\_transaction** (nullable, integer)  
The number of days since the oldest transaction available to Plaid for this account. This measure, combined with Plaid connection history, can be used to infer the age of the account

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "bank_account_insights": {
    "item_id": "515cd85321d3649aecddc015",
    "accounts": [
      {
        "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
        "type": "depository",
        "subtype": "checking",
        "attributes": {
          "days_since_first_plaid_connection": 1,
          "is_account_closed": false,
          "is_account_frozen_or_restricted": false,
          "total_plaid_connections_count": 1,
          "plaid_connections_count_7d": 1,
          "plaid_connections_count_30d": 1,
          "failed_plaid_non_oauth_authentication_attempts_count_3d": 1,
          "plaid_non_oauth_authentication_attempts_count_3d": 1,
          "failed_plaid_non_oauth_authentication_attempts_count_7d": 1,
          "plaid_non_oauth_authentication_attempts_count_7d": 1,
          "failed_plaid_non_oauth_authentication_attempts_count_30d": 1,
          "plaid_non_oauth_authentication_attempts_count_30d": 1,
          "distinct_ip_addresses_count_3d": 1,
          "distinct_ip_addresses_count_7d": 1,
          "distinct_ip_addresses_count_30d": 1,
          "distinct_ip_addresses_count_90d": 1,
          "distinct_user_agents_count_3d": 1,
          "distinct_user_agents_count_7d": 1,
          "distinct_user_agents_count_30d": 1,
          "distinct_user_agents_count_90d": 1,
          "address_change_count_28d": 1,
          "email_change_count_28d": 2,
          "phone_change_count_28d": 1,
          "address_change_count_90d": 3,
          "email_change_count_90d": 4,
          "phone_change_count_90d": 2,
          "days_since_account_opening": 365,
          "days_since_first_observed_transaction": 180
        }
      }
    ]
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/history/list 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### List a Beacon User's history 

List all changes to the Beacon User in reverse-chronological order.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

**cursor** (string)  
An identifier that determines which page of results you receive.

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

```javascript
const request: BeaconUserHistoryListRequest = {
  beacon_user_id: 'becusr_11111111111111',
};


try {
  const response = await plaidClient.beaconUserHistoryList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

\[string\]

**beacon\_users** (\[object\])  
An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

**beacon\_users->id** (string)  
ID of the associated Beacon User.

**beacon\_users->version** (integer)  
The version field begins with 1 and increments each time the user is updated.

**beacon\_users->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**beacon\_users->updated\_at** (string)  
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: date-time

**beacon\_users->status** (string)  
A status of a Beacon User. rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. pending\_review: The Beacon User has been marked for review. cleared: The Beacon User has been cleared of fraud. Possible values: rejected, pending\_review, cleared

**beacon\_users->program\_id** (string)  
ID of the associated Beacon Program.

**beacon\_users->client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**beacon\_users->user** (object)  
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

**beacon\_users->user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**beacon\_users->user->name** (object)  
The full name for a given Beacon User.

**beacon\_users->user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**beacon\_users->user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**beacon\_users->user->address** (object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code

**beacon\_users->user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**beacon\_users->user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**beacon\_users->user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**beacon\_users->user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**beacon\_users->user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**beacon\_users->user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**beacon\_users->user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**beacon\_users->user->phone\_number** (nullable, string)  
A phone number in E.164 format.

**beacon\_users->user->id\_number** (nullable, object)  
The ID number associated with a Beacon User.

**beacon\_users->user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**beacon\_users->user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**beacon\_users->user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

string

**beacon\_users->user->depository\_accounts** (\[object\])  
The last 2-4 numeric characters of this account’s account number.

**beacon\_users->user->depository\_accounts->routing\_number** (string)  
The routing number of the account.

**beacon\_users->user->depository\_accounts->added\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**beacon\_users->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**beacon\_users->audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**beacon\_users->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**beacon\_users->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "beacon_users": [
    {
      "item_ids": [
        "515cd85321d3649aecddc015"
      ],
      "id": "becusr_42cF1MNo42r9Xj",
      "version": 1,
      "created_at": "2020-07-24T03:26:02Z",
      "updated_at": "2020-07-24T03:26:02Z",
      "status": "cleared",
      "program_id": "becprg_11111111111111",
      "client_user_id": "your-db-id-3b24110",
      "user": {
        "date_of_birth": "1990-05-29",
        "name": {
          "given_name": "Leslie",
          "family_name": "Knope"
        },
        "address": {
          "street": "123 Main St.",
          "street2": "Unit 42",
          "city": "Pawnee",
          "region": "IN",
          "postal_code": "46001",
          "country": "US"
        },
        "email_address": "user@example.com",
        "phone_number": "+19876543212",
        "id_number": {
          "value": "123456789",
          "type": "us_ssn"
        },
        "ip_address": "192.0.2.42",
        "depository_accounts": [
          {
            "account_mask": "4000",
            "routing_number": "021000021",
            "added_at": "2020-07-24T03:26:02Z"
          }
        ]
      },
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report/create 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Create a Beacon Report 

Create a fraud report for a given Beacon User.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

**type** (required, string)  
The type of Beacon Report. first\_party: If this is the same individual as the one who submitted the KYC. stolen: If this is a different individual from the one who submitted the KYC. synthetic: If this is an individual using fabricated information. account\_takeover: If this individual's account was compromised. unknown: If you aren't sure who committed the fraud. Possible values: first\_party, stolen, synthetic, account\_takeover, unknown

**fraud\_date** (required, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**fraud\_amount** (object)  
The amount and currency of the fraud or attempted fraud. fraud\_amount should be omitted to indicate an unknown fraud amount.

**fraud\_amount->iso\_currency\_code** (required, string)  
An ISO-4217 currency code. Possible values: USD

**fraud\_amount->value** (required, number)  
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23). Format: double

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

```javascript
const request: BeaconReportCreateRequest = {
  beacon_user_id: 'becusr_11111111111111',
  type: 'first_party',
  fraud_date: '1975-01-18',
};


try {
  const response = await plaidClient.beaconReportCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Beacon Report.

**beacon\_user\_id** (string)  
ID of the associated Beacon User.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**type** (string)  
The type of Beacon Report. first\_party: If this is the same individual as the one who submitted the KYC. stolen: If this is a different individual from the one who submitted the KYC. synthetic: If this is an individual using fabricated information. account\_takeover: If this individual's account was compromised. data\_breach: If this individual's data was compromised in a breach. unknown: If you aren't sure who committed the fraud. Possible values: first\_party, stolen, synthetic, account\_takeover, data\_breach, unknown

**fraud\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**event\_date** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**fraud\_amount** (nullable, object)  
The amount and currency of the fraud or attempted fraud. fraud\_amount should be omitted to indicate an unknown fraud amount.

**fraud\_amount->iso\_currency\_code** (string)  
An ISO-4217 currency code. Possible values: USD

**fraud\_amount->value** (number)  
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23). Format: double

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "becrpt_11111111111111",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "created_at": "2020-07-24T03:26:02Z",
  "type": "first_party",
  "fraud_date": "1990-05-29",
  "event_date": "1990-05-29",
  "fraud_amount": {
    "iso_currency_code": "USD",
    "value": 100
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report/get 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get a Beacon Report 

Returns a Beacon report for a given Beacon report id.

#### Request fields 

**beacon\_report\_id** (required, string)  
ID of the associated Beacon Report.

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

```javascript
const request: BeaconReportGetRequest = {
  beacon_report_id: 'becrpt_11111111111111',
};


try {
  const response = await plaidClient.beaconReportGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Beacon Report.

**beacon\_user\_id** (string)  
ID of the associated Beacon User.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**type** (string)  
The type of Beacon Report. first\_party: If this is the same individual as the one who submitted the KYC. stolen: If this is a different individual from the one who submitted the KYC. synthetic: If this is an individual using fabricated information. account\_takeover: If this individual's account was compromised. data\_breach: If this individual's data was compromised in a breach. unknown: If you aren't sure who committed the fraud. Possible values: first\_party, stolen, synthetic, account\_takeover, data\_breach, unknown

**fraud\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**event\_date** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**fraud\_amount** (nullable, object)  
The amount and currency of the fraud or attempted fraud. fraud\_amount should be omitted to indicate an unknown fraud amount.

**fraud\_amount->iso\_currency\_code** (string)  
An ISO-4217 currency code. Possible values: USD

**fraud\_amount->value** (number)  
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23). Format: double

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "becrpt_11111111111111",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "created_at": "2020-07-24T03:26:02Z",
  "type": "first_party",
  "fraud_date": "1990-05-29",
  "event_date": "1990-05-29",
  "fraud_amount": {
    "iso_currency_code": "USD",
    "value": 100
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report/list 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### List Beacon Reports for a Beacon User 

Use the [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) endpoint to view all Beacon Reports you created for a specific Beacon User. The reports returned by this endpoint are exclusively reports you created for a specific user. A Beacon User can only have one active report at a time, but a new report can be created if a previous report has been deleted. The results from this endpoint are paginated; the `next_cursor` field will be populated if there is another page of results that can be retrieved. To fetch the next page, pass the `next_cursor` value as the `cursor` parameter in the next request.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

**cursor** (string)  
An identifier that determines which page of results you receive.

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

```javascript
const request: BeaconReportListRequest = {
  beacon_user_id: 'becusr_11111111111111',
};


try {
  const response = await plaidClient.beaconReportList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**beacon\_reports** (\[object\])  
ID of the associated Beacon Report.

**beacon\_reports->beacon\_user\_id** (string)  
ID of the associated Beacon User.

**beacon\_reports->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**beacon\_reports->type** (string)  
The type of Beacon Report. first\_party: If this is the same individual as the one who submitted the KYC. stolen: If this is a different individual from the one who submitted the KYC. synthetic: If this is an individual using fabricated information. account\_takeover: If this individual's account was compromised. data\_breach: If this individual's data was compromised in a breach. unknown: If you aren't sure who committed the fraud. Possible values: first\_party, stolen, synthetic, account\_takeover, data\_breach, unknown

**beacon\_reports->fraud\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**beacon\_reports->event\_date** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**beacon\_reports->fraud\_amount** (nullable, object)  
The amount and currency of the fraud or attempted fraud. fraud\_amount should be omitted to indicate an unknown fraud amount.

**beacon\_reports->fraud\_amount->iso\_currency\_code** (string)  
An ISO-4217 currency code. Possible values: USD

**beacon\_reports->fraud\_amount->value** (number)  
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23). Format: double

**beacon\_reports->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**beacon\_reports->audit\_trail->source** (string)  
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system. bulk\_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk\_import. Possible values: dashboard, api, system, bulk\_import

**beacon\_reports->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**beacon\_reports->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "beacon_reports": [
    {
      "id": "becrpt_11111111111111",
      "beacon_user_id": "becusr_42cF1MNo42r9Xj",
      "created_at": "2020-07-24T03:26:02Z",
      "type": "first_party",
      "fraud_date": "1990-05-29",
      "event_date": "1990-05-29",
      "fraud_amount": {
        "iso_currency_code": "USD",
        "value": 100
      },
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report\_syndication/get 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get a Beacon Report Syndication 

Returns a Beacon Report Syndication for a given Beacon Report Syndication id.

#### Request fields 

**beacon\_report\_syndication\_id** (required, string)  
ID of the associated Beacon Report Syndication.

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

```javascript
const request: BeaconReportSyndicationGetRequest = {
  beacon_report_syndication_id: 'becrsn_11111111111111',
};


try {
  const response = await plaidClient.beaconReportSyndicationGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Beacon Report Syndication.

**beacon\_user\_id** (string)  
ID of the associated Beacon User.

**report** (object)  
A subset of information from a Beacon Report that has been syndicated to a matching Beacon User in your program. The id field in the response is the ID of the original report that was syndicated. If the original report was created by your organization, the field will be filled with the ID of the report. Otherwise, the field will be null indicating that the original report was created by another Beacon customer.

**report->id** (nullable, string)  
ID of the associated Beacon Report.

**report->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**report->type** (string)  
The type of Beacon Report. first\_party: If this is the same individual as the one who submitted the KYC. stolen: If this is a different individual from the one who submitted the KYC. synthetic: If this is an individual using fabricated information. account\_takeover: If this individual's account was compromised. data\_breach: If this individual's data was compromised in a breach. unknown: If you aren't sure who committed the fraud. Possible values: first\_party, stolen, synthetic, account\_takeover, data\_breach, unknown

**report->fraud\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**report->event\_date** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**analysis** (object)  
Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to.

**analysis->address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->date\_of\_birth** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->email\_address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->name** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->id\_number** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->ip\_address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->phone\_number** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

string

**analysis->depository\_accounts** (\[object\])  
The last 2-4 numeric characters of this account’s account number.

**analysis->depository\_accounts->routing\_number** (string)  
The routing number of the account.

**analysis->depository\_accounts->match\_status** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "becrsn_11111111111111",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "report": {
    "id": "becrpt_11111111111111",
    "created_at": "2020-07-24T03:26:02Z",
    "type": "first_party",
    "fraud_date": "1990-05-29",
    "event_date": "1990-05-29"
  },
  "analysis": {
    "address": "match",
    "date_of_birth": "match",
    "email_address": "match",
    "name": "match",
    "id_number": "match",
    "ip_address": "match",
    "phone_number": "match",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "match_status": "match"
      }
    ]
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report\_syndication/list 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### List Beacon Report Syndications for a Beacon User 

Use the [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) endpoint to view all Beacon Reports that have been syndicated to a specific Beacon User. This endpoint returns Beacon Report Syndications which are references to Beacon Reports created either by you, or another Beacon customer, that matched the specified Beacon User. A Beacon User can have multiple active Beacon Report Syndications at once. The results from this endpoint are paginated; the `next_cursor` field will be populated if there is another page of results that can be retrieved. To fetch the next page, pass the `next_cursor` value as the `cursor` parameter in the next request.

#### Request fields 

**beacon\_user\_id** (required, string)  
ID of the associated Beacon User.

**cursor** (string)  
An identifier that determines which page of results you receive.

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

```javascript
const request: BeaconReportSyndicationListRequest = {
  beacon_user_id: 'becusr_11111111111111',
};


try {
  const response = await plaidClient.beaconReportSyndicationList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**beacon\_report\_syndications** (\[object\])  
ID of the associated Beacon Report Syndication.

**beacon\_report\_syndications->beacon\_user\_id** (string)  
ID of the associated Beacon User.

**beacon\_report\_syndications->report** (object)  
A subset of information from a Beacon Report that has been syndicated to a matching Beacon User in your program. The id field in the response is the ID of the original report that was syndicated. If the original report was created by your organization, the field will be filled with the ID of the report. Otherwise, the field will be null indicating that the original report was created by another Beacon customer.

**beacon\_report\_syndications->report->id** (nullable, string)  
ID of the associated Beacon Report.

**beacon\_report\_syndications->report->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**beacon\_report\_syndications->report->type** (string)  
The type of Beacon Report. first\_party: If this is the same individual as the one who submitted the KYC. stolen: If this is a different individual from the one who submitted the KYC. synthetic: If this is an individual using fabricated information. account\_takeover: If this individual's account was compromised. data\_breach: If this individual's data was compromised in a breach. unknown: If you aren't sure who committed the fraud. Possible values: first\_party, stolen, synthetic, account\_takeover, data\_breach, unknown

**beacon\_report\_syndications->report->fraud\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**beacon\_report\_syndications->report->event\_date** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**beacon\_report\_syndications->analysis** (object)  
Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to.

**beacon\_report\_syndications->analysis->address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**beacon\_report\_syndications->analysis->date\_of\_birth** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**beacon\_report\_syndications->analysis->email\_address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**beacon\_report\_syndications->analysis->name** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**beacon\_report\_syndications->analysis->id\_number** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**beacon\_report\_syndications->analysis->ip\_address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**beacon\_report\_syndications->analysis->phone\_number** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

string

**beacon\_report\_syndications->analysis->depository\_accounts** (\[object\])  
The last 2-4 numeric characters of this account’s account number.

**beacon\_report\_syndications->analysis->depository\_accounts->routing\_number** (string)  
The routing number of the account.

**beacon\_report\_syndications->analysis->depository\_accounts->match\_status** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "beacon_report_syndications": [
    {
      "id": "becrsn_11111111111111",
      "beacon_user_id": "becusr_42cF1MNo42r9Xj",
      "report": {
        "id": "becrpt_11111111111111",
        "created_at": "2020-07-24T03:26:02Z",
        "type": "first_party",
        "fraud_date": "1990-05-29",
        "event_date": "1990-05-29"
      },
      "analysis": {
        "address": "match",
        "date_of_birth": "match",
        "email_address": "match",
        "name": "match",
        "id_number": "match",
        "ip_address": "match",
        "phone_number": "match",
        "depository_accounts": [
          {
            "account_mask": "4000",
            "routing_number": "021000021",
            "match_status": "match"
          }
        ]
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/duplicate/get 

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get a Beacon Duplicate 

Returns a Beacon Duplicate for a given Beacon Duplicate id.  
A Beacon Duplicate represents a pair of similar Beacon Users within your organization.  
Two Beacon User revisions are returned for each Duplicate record in either the `beacon_user1` or `beacon_user2` response fields.  
The `analysis` field in the response indicates which fields matched between `beacon_user1` and `beacon_user2`.

#### Request fields 

**beacon\_duplicate\_id** (required, string)  
ID of the associated Beacon Duplicate.

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

```javascript
const request: BeaconDuplicateGetRequest = {
  beacon_duplicate_id: 'becdup_11111111111111',
};


try {
  const response = await plaidClient.beaconDuplicateGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Beacon Duplicate.

**beacon\_user1** (object)  
A Beacon User Revision identifies a Beacon User at some point in its revision history.

**beacon\_user1->id** (string)  
ID of the associated Beacon User.

**beacon\_user1->version** (integer)  
The version field begins with 1 and increments with each subsequent revision.

**beacon\_user2** (object)  
A Beacon User Revision identifies a Beacon User at some point in its revision history.

**beacon\_user2->id** (string)  
ID of the associated Beacon User.

**beacon\_user2->version** (integer)  
The version field begins with 1 and increments with each subsequent revision.

**analysis** (object)  
Analysis of which fields matched between one Beacon User and another.

**analysis->address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->date\_of\_birth** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->email\_address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->name** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->id\_number** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->ip\_address** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**analysis->phone\_number** (string)  
An enum indicating the match type between two Beacon Users. match indicates that the provided input data was a strong match against the other Beacon User. partial\_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. no\_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: match, partial\_match, no\_match, no\_data

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "becdup_11111111111111",
  "beacon_user1": {
    "id": "becusr_42cF1MNo42r9Xj",
    "version": 1
  },
  "beacon_user2": {
    "id": "becusr_42cF1MNo42r9Xj",
    "version": 1
  },
  "analysis": {
    "address": "match",
    "date_of_birth": "match",
    "email_address": "match",
    "name": "match",
    "id_number": "match",
    "ip_address": "match",
    "phone_number": "match"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

### Webhooks 

A user in `cleared` status may change to a `pending_review` status after a Beacon Report Syndication is received, which would trigger both a `USER_STATUS_UPDATED` as well as a `REPORT_SYNDICATION_CREATED` webhook. New Beacon Users may also be flagged as duplicates of another user, which triggers a `DUPLICATE_DETECTED` webhook. Beacon Reports created and managed by your account will trigger `REPORT_CREATED` and `REPORT_UPDATED` webhooks, and may also result in a `USER_STATUS_UPDATED` if the user status is changed from `cleared` to `rejected` at that time.

\=\*=\*=\*=

#### USER\_STATUS\_UPDATED 

Fired when a Beacon User status has changed, which can occur manually via the dashboard or when information is reported to the Beacon network.

#### Properties 

**webhook\_type** (string)  
BEACON

**webhook\_code** (string)  
USER\_STATUS\_UPDATED

**beacon\_user\_id** (string)  
The ID of the associated Beacon user.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "USER_STATUS_UPDATED",
  "beacon_user_id": "becusr_4WciCrtbxF76T8",
  "environment": "production"
}
```

\=\*=\*=\*=

#### REPORT\_CREATED 

Fired when one of your Beacon Users is first reported to the Beacon network.

#### Properties 

**webhook\_type** (string)  
BEACON

**webhook\_code** (string)  
REPORT\_CREATED

**beacon\_report\_id** (string)  
The ID of the associated Beacon Report.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "REPORT_CREATED",
  "beacon_report_id": "becrpt_2zugxV6hWQZG91",
  "environment": "production"
}
```

\=\*=\*=\*=

#### REPORT\_UPDATED 

Fired when one of your existing Beacon Reports has been modified or removed from the Beacon Network.

#### Properties 

**webhook\_type** (string)  
BEACON

**webhook\_code** (string)  
REPORT\_UPDATED

**beacon\_report\_id** (string)  
The ID of the associated Beacon Report.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "REPORT_UPDATED",
  "beacon_report_id": "becrpt_2zugxV6hWQZG91",
  "environment": "production"
}
```

\=\*=\*=\*=

#### REPORT\_SYNDICATION\_CREATED 

Fired when a report created on the Beacon Network matches with one of your Beacon Users.

#### Properties 

**webhook\_type** (string)  
BEACON

**webhook\_code** (string)  
REPORT\_SYNDICATION\_CREATED

**beacon\_report\_syndication\_id** (string)  
The ID of the associated Beacon Report Syndication.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "REPORT_SYNDICATION_CREATED",
  "beacon_report_syndication_id": "becrsn_eZPgiiv3JH8rfT",
  "environment": "production"
}
```

\=\*=\*=\*=

#### DUPLICATE\_DETECTED 

Fired when a Beacon User created within your organization matches one of your existing users.

#### Properties 

**webhook\_type** (string)  
BEACON

**webhook\_code** (string)  
DUPLICATE\_DETECTED

**beacon\_duplicate\_id** (string)  
The ID of the associated Beacon Duplicate.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "DUPLICATE_DETECTED",
  "beacon_duplicate_id": "becdup_erJcFn97r9sugZ",
  "environment": "production"
}
```

---


# API - Consumer Report (by Plaid Check) | Plaid Docs

Plaid Check 
============

#### API reference for Plaid Check endpoints and webhooks 

| Endpoints |  |
| --- | --- |
| [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) | Generate a new Consumer Report for your user with the latest data |
| [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) | Retrieve the base Consumer Report for your user |
| [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) | Retrieve cash flow insights from your user's banks |
| [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) | Retrieve connection insights from the Plaid network (beta) |
| [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) | Retrieve cash flow insights from our partners |
| [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) | Retrieve Consumer Reports in PDF format |
| [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) | Retrieve Verification Reports (VOA, Employment Refresh) for your user |
| [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) | Get Cash Flow Updates (beta) |
| [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) | Subscribe to Cash Flow Updates (beta) |
| [/cra/monitoring\_insights/unsubscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsunsubscribe) | Unsubscribe from Cash Flow Updates (beta) |

| See also |  |
| --- | --- |
| [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) | Create a token for initializing a Link session with Plaid Check |
| [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | Create a user ID and token for use with Plaid Check |
| [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) | Update an existing user token to work with Plaid Check, or change user details |
| [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) | Removes the user and their relevant data |
| [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) | Returns Items associated with a user along with their corresponding statuses |
| [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) | Manually trigger a cashflow insights update for a user (Sandbox only) |

| Webhooks |  |
| --- | --- |
| [CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#check_report_ready) | A Consumer Report is ready to be retrieved |
| [CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#check_report_failed) | Plaid Check failed to create a report |

| Cash Flow Updates (beta) webhooks |  |
| --- | --- |
| [INSIGHTS\_UPDATED](https://plaid.com/docs/api/products/check/index.html.md#insights_updated) | Insights have been refreshed |
| [LARGE\_DEPOSIT\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#large_deposit_detected) | A large deposit over $5000 has been detected |
| [LOW\_BALANCE\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#low_balance_detected) | Current balance has crossed below $100 |
| [NEW\_LOAN\_PAYMENT\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#new_loan_payment_detected) | A new loan payment has been detected |
| [NSF\_OVERDRAFT\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#nsf_overdraft_detected) | An overdraft transaction has been detected |

\=\*=\*=\*=

#### /cra/check\_report/create 

#### Create a Consumer Report 

[/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) creates a Consumer Report powered by Plaid Check. You can call this endpoint to create a new report if `consumer_report_permissible_purpose` was omitted during Link token creation. If you did provide a `consumer_report_permissible_purpose` during Link token creation, then Plaid Check will automatically begin creating a Consumer Report once the user completes the Link process, and it is not necessary to call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) before retrieving the report.  
[/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) can also be used to refresh data in an existing report. A Consumer Report will last for 24 hours before expiring; you should call any `/get` endpoints on the report before it expires. If a report expires, you can call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) again to re-generate it. Note that refreshing or regenerating a report is a billable event.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**webhook** (required, string)  
The destination URL to which webhooks will be sent

**days\_requested** (required, integer)  
The number of days of data to request for the report. Default value is 365; maximum is 731; minimum is 180. If a value lower than 180 is provided, a minimum of 180 days of history will be requested. Maximum: 731

**days\_required** (integer)  
The minimum number of days of data required for the report to be successfully generated. Maximum: 184

**client\_report\_id** (string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**products** (\[string\])  
Specifies a list of products that will be eagerly generated when creating the report (in addition to the Base Report, which is always eagerly generated). These products will be made available before a success webhook is sent. Use this option to minimize response latency for product /get endpoints. Note that specifying cra\_partner\_insights in this field will trigger a billable event. Other products are not billed until the respective reports are fetched via product-specific /get endpoints. Min items: 1 Possible values: cra\_income\_insights, cra\_cashflow\_insights, cra\_partner\_insights, cra\_network\_insights

**base\_report** (object)  
Defines configuration options to generate a Base Report

**base\_report->client\_report\_id** (deprecated, string)  
Client-generated identifier, which can be used by lenders to track loan applications. This field is deprecated. Use the client\_report\_id field at the top level of the request instead.

**base\_report->gse\_options** (object)  
Specifies options for creating reports that can be shared with GSEs for mortgage verification.

**base\_report->gse\_options->report\_types** (required, \[string\])  
Specifies which types of reports should be made available to GSEs. Possible values: VOA, EMPLOYMENT\_REFRESH

**base\_report->require\_identity** (boolean)  
Indicates that the report must include identity information. If identity information is not available, the report will fail.

**cashflow\_insights** (object)  
Defines configuration options to generate Cashflow Insights

**cashflow\_insights->attributes\_version** (string)  
The version of cashflow attributes Possible values: v1.0, v2.0

**partner\_insights** (object)  
Defines configuration to generate Partner Insights.

**partner\_insights->prism\_products** (deprecated, \[string\])  
The specific Prism Data products to return. If none are passed in, then all products will be returned. Possible values: insights, scores

**partner\_insights->prism\_versions** (object)  
The versions of Prism products to evaluate

**partner\_insights->prism\_versions->firstdetect** (string)  
The version of Prism FirstDetect. If not specified, will default to v3. Possible values: 3, null

**partner\_insights->prism\_versions->detect** (string)  
The version of Prism Detect Possible values: 4, null

**partner\_insights->prism\_versions->cashscore** (string)  
The version of Prism CashScore. If not specified, will default to v3. Possible values: 4, 3, null

**partner\_insights->prism\_versions->extend** (string)  
The version of Prism Extend Possible values: 4, null

**partner\_insights->prism\_versions->insights** (string)  
The version of Prism Insights. If not specified, will default to v3. Possible values: 4, 3, null

**consumer\_report\_permissible\_purpose** (required, string)  
Describes the reason you are generating a Consumer Report for this user. 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). EMPLOYMENT: For employment purposes pursuant to FCRA 604(a)(3)(B), including hiring, retention and promotion purposes. 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. Possible values: ACCOUNT\_REVIEW\_CREDIT, ACCOUNT\_REVIEW\_NON\_CREDIT, EMPLOYMENT, EXTENSION\_OF\_CREDIT, LEGITIMATE\_BUSINESS\_NEED\_TENANT\_SCREENING, LEGITIMATE\_BUSINESS\_NEED\_OTHER, WRITTEN\_INSTRUCTION\_PREQUALIFICATION, WRITTEN\_INSTRUCTION\_OTHER

```javascript
try {
  const response = await client.craCheckReportCreate({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
    webhook: 'https://sample-web-hook.com',
    days_requested: 365,
    consumer_report_permissible_purpose: 'LEGITIMATE_BUSINESS_NEED_OTHER',
  });
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "LhQf0THi8SH1yJm"
}
```

\=\*=\*=\*=

#### /cra/check\_report/base\_report/get 

#### Retrieve a Base Report 

This endpoint allows you to retrieve the Base Report for your user, allowing you to receive comprehensive bank account and cash flow data. You should call this endpoint after you've received a `CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn't have sufficient data to generate the base report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
try {
  const response = await client.craCheckReportBaseReportGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  });
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**report** (object)  
An object representing a Base Report

**report->report\_id** (string)  
A unique ID identifying an Base Report. Like all Plaid identifiers, this ID is case sensitive.

**report->date\_generated** (string)  
The date and time when the Base Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time

**report->days\_requested** (number)  
The number of days of transaction history requested.

**report->client\_report\_id** (nullable, string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**report->items** (\[object\])  
Data returned by Plaid about each of the Items included in the Base Report.

**report->items->institution\_name** (string)  
The full financial institution name associated with the Item.

**report->items->institution\_id** (string)  
The id of the financial institution associated with the Item.

**report->items->date\_last\_updated** (string)  
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format. Format: date-time

**report->items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**report->items->accounts** (\[object\])  
Data about each of the accounts open on the Item.

**report->items->accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->items->accounts->balances** (object)  
Information about an account's balances.

**report->items->accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**report->items->accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**report->items->accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**report->items->accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->items->accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get. This field is only used and expected when the institution is ins\_128026 (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID\_REQUEST error with the code of INVALID\_FIELD will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an INVALID\_REQUEST error with the code of LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE will be returned with the most recent timestamp for the requested account contained in the response. Format: date-time

**report->items->accounts->balances->average\_balance** (nullable, number)  
The average historical balance for the entire report Format: double

**report->items->accounts->balances->average\_monthly\_balances** (\[object\])  
The average historical balance of each calendar month

**report->items->accounts->balances->average\_monthly\_balances->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

**report->items->accounts->balances->average\_monthly\_balances->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

**report->items->accounts->balances->average\_monthly\_balances->average\_balance** (object)  
This contains an amount, denominated in the currency specified by either iso\_currency\_code or unofficial\_currency\_code

**report->items->accounts->balances->average\_monthly\_balances->average\_balance->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->balances->average\_monthly\_balances->average\_balance->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->balances->average\_monthly\_balances->average\_balance->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->balances->most\_recent\_thirty\_day\_average\_balance** (nullable, number)  
The average historical balance from the most recent 30 days Format: double

**report->items->accounts->consumer\_disputes** (\[object\])  
The information about previously submitted valid dispute statements by the consumer

**report->items->accounts->consumer\_disputes->consumer\_dispute\_id** (deprecated, string)  
(Deprecated) A unique identifier (UUID) of the consumer dispute that can be used for troubleshooting

**report->items->accounts->consumer\_disputes->dispute\_field\_create\_date** (string)  
Date of the disputed field (e.g. transaction date), in an ISO 8601 format (YYYY-MM-DD) Format: date

**report->items->accounts->consumer\_disputes->category** (string)  
Type of data being disputed by the consumer Possible values: TRANSACTION, BALANCE, IDENTITY, OTHER

**report->items->accounts->consumer\_disputes->statement** (string)  
Text content of dispute

**report->items->accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**report->items->accounts->metadata** (object)  
Metadata about the extracted account.

**report->items->accounts->metadata->start\_date** (nullable, string)  
The beginning of the range of the financial institution provided data for the account, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**report->items->accounts->metadata->end\_date** (nullable, string)  
The end of the range of the financial institution provided data for the account, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**report->items->accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**report->items->accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**report->items->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**report->items->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**report->items->accounts->days\_available** (number)  
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.

**report->items->accounts->transactions** (\[object\])  
Transaction history associated with the account. Transaction history returned by endpoints such as /transactions/get or /investments/transactions/get will be returned in the top-level transactions field instead.

**report->items->accounts->transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**report->items->accounts->transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: double

**report->items->accounts->transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**report->items->accounts->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->items->accounts->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**report->items->accounts->transactions->credit\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the taxonomy csv file for a full list of credit categories.

**report->items->accounts->transactions->credit\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**report->items->accounts->transactions->credit\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**report->items->accounts->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**report->items->accounts->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**report->items->accounts->transactions->date\_transacted** (nullable, string)  
The date on which the transaction took place, in IS0 8601 format.

**report->items->accounts->transactions->location** (object)  
A representation of where a transaction took place

**report->items->accounts->transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**report->items->accounts->transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**report->items->accounts->transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**report->items->accounts->transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**report->items->accounts->transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**report->items->accounts->transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**report->items->accounts->transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**report->items->accounts->transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**report->items->accounts->transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**report->items->accounts->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->items->accounts->transactions->account\_owner** (nullable, string)  
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.

**report->items->accounts->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->items->accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. This array can also be empty if no owners are found.

**report->items->accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**report->items->accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->phone\_numbers->data** (string)  
The phone number.

**report->items->accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**report->items->accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**report->items->accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->emails->data** (string)  
The email address.

**report->items->accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**report->items->accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**report->items->accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->items->accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**report->items->accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**report->items->accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**report->items->accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**report->items->accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**report->items->accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**report->items->accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**report->items->accounts->ownership\_type** (nullable, string)  
How an asset is owned. association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust. Possible values: null, individual, joint, association, trust

**report->items->accounts->account\_insights** (deprecated, object)  
Calculated insights derived from transaction-level data. This field has been deprecated in favor of Base Report attributes aggregated across accounts and will be removed in a future release.

**report->items->accounts->account\_insights->oldest\_transaction\_date** (nullable, string)  
Date of the earliest transaction for the account. Format: date

**report->items->accounts->account\_insights->most\_recent\_transaction\_date** (nullable, string)  
Date of the most recent transaction for the account. Format: date

**report->items->accounts->account\_insights->days\_available** (integer)  
Number of days days available for the account.

**report->items->accounts->account\_insights->average\_days\_between\_transactions** (number)  
Average number of days between sequential transactions

**report->items->accounts->account\_insights->longest\_gaps\_between\_transactions** (\[object\])  
Longest gap between sequential transactions in a time period. This array can include multiple time periods.

**report->items->accounts->account\_insights->longest\_gaps\_between\_transactions->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->longest\_gaps\_between\_transactions->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->longest\_gaps\_between\_transactions->days** (nullable, integer)  
Largest number of days between sequential transactions for this time period.

**report->items->accounts->account\_insights->number\_of\_inflows** (\[object\])  
The number of debits into the account. This array will be empty for non-depository accounts.

**report->items->accounts->account\_insights->number\_of\_inflows->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->number\_of\_inflows->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->number\_of\_inflows->count** (integer)  
The number of credits or debits out of the account for this time period.

**report->items->accounts->account\_insights->average\_inflow\_amounts** (\[object\])  
Average amount of debit transactions into the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->account\_insights->average\_inflow\_amounts->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->average\_inflow\_amounts->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->average\_inflow\_amounts->total\_amount** (object)  
This contains an amount, denominated in the currency specified by either iso\_currency\_code or unofficial\_currency\_code

**report->items->accounts->account\_insights->average\_inflow\_amounts->total\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->account\_insights->average\_inflow\_amounts->total\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->account\_insights->average\_inflow\_amounts->total\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->account\_insights->number\_of\_outflows** (\[object\])  
The number of outflows from the account. This array will be empty for non-depository accounts.

**report->items->accounts->account\_insights->number\_of\_outflows->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->number\_of\_outflows->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->number\_of\_outflows->count** (integer)  
The number of credits or debits out of the account for this time period.

**report->items->accounts->account\_insights->average\_outflow\_amounts** (\[object\])  
Average amount of transactions out of the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->account\_insights->average\_outflow\_amounts->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->average\_outflow\_amounts->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->accounts->account\_insights->average\_outflow\_amounts->total\_amount** (object)  
This contains an amount, denominated in the currency specified by either iso\_currency\_code or unofficial\_currency\_code

**report->items->accounts->account\_insights->average\_outflow\_amounts->total\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->account\_insights->average\_outflow\_amounts->total\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->account\_insights->average\_outflow\_amounts->total\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->account\_insights->number\_of\_days\_no\_transactions** (integer)  
Number of days with no transactions

**report->items->accounts->attributes** (object)  
Calculated attributes derived from transaction-level data.

**report->items->accounts->attributes->is\_primary\_account** (nullable, boolean)  
Prediction indicator of whether the account is a primary account. Only one account per account type across the items connected will have a value of true.

**report->items->accounts->attributes->primary\_account\_score** (nullable, number)  
Value ranging from 0-1. The higher the score, the more confident we are of the account being the primary account.

**report->items->accounts->attributes->nsf\_overdraft\_transactions\_count** (integer)  
The number of NSF and overdraft fee transactions in the time range for the report in the given account.

**report->items->accounts->attributes->nsf\_overdraft\_transactions\_count\_30d** (integer)  
The number of NSF and overdraft fee transactions in the last 30 days for a given account.

**report->items->accounts->attributes->nsf\_overdraft\_transactions\_count\_60d** (integer)  
The number of NSF and overdraft fee transactions in the last 60 days for a given account.

**report->items->accounts->attributes->nsf\_overdraft\_transactions\_count\_90d** (integer)  
The number of NSF and overdraft fee transactions in the last 90 days for a given account.

**report->items->accounts->attributes->total\_inflow\_amount** (nullable, object)  
Total amount of debit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_inflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_inflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_inflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_inflow\_amount\_30d** (nullable, object)  
Total amount of debit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_inflow\_amount\_30d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_inflow\_amount\_30d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_inflow\_amount\_30d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_inflow\_amount\_60d** (nullable, object)  
Total amount of debit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_inflow\_amount\_60d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_inflow\_amount\_60d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_inflow\_amount\_60d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_inflow\_amount\_90d** (nullable, object)  
Total amount of debit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_inflow\_amount\_90d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_inflow\_amount\_90d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_inflow\_amount\_90d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_outflow\_amount** (nullable, object)  
Total amount of credit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_outflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_outflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_outflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_outflow\_amount\_30d** (nullable, object)  
Total amount of credit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_outflow\_amount\_30d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_outflow\_amount\_30d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_outflow\_amount\_30d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_outflow\_amount\_60d** (nullable, object)  
Total amount of credit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_outflow\_amount\_60d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_outflow\_amount\_60d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_outflow\_amount\_60d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->accounts->attributes->total\_outflow\_amount\_90d** (nullable, object)  
Total amount of credit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**report->items->accounts->attributes->total\_outflow\_amount\_90d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->items->accounts->attributes->total\_outflow\_amount\_90d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->accounts->attributes->total\_outflow\_amount\_90d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes** (object)  
Calculated attributes derived from transaction-level data, aggregated across accounts.

**report->attributes->nsf\_overdraft\_transactions\_count** (integer)  
The number of NSF and overdraft fee transactions in the time range for the report in the given report.

**report->attributes->nsf\_overdraft\_transactions\_count\_30d** (integer)  
The number of NSF and overdraft fee transactions in the last 30 days for a given report.

**report->attributes->nsf\_overdraft\_transactions\_count\_60d** (integer)  
The number of NSF and overdraft fee transactions in the last 60 days for a given report.

**report->attributes->nsf\_overdraft\_transactions\_count\_90d** (integer)  
The number of NSF and overdraft fee transactions in the last 90 days for a given report.

**report->attributes->total\_inflow\_amount** (nullable, object)  
Total amount of debit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_inflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_inflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_inflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_inflow\_amount\_30d** (nullable, object)  
Total amount of debit transactions into the report's accounts in the last 30 days. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_inflow\_amount\_30d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_inflow\_amount\_30d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_inflow\_amount\_30d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_inflow\_amount\_60d** (nullable, object)  
Total amount of debit transactions into the report's accounts in the last 60 days. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_inflow\_amount\_60d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_inflow\_amount\_60d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_inflow\_amount\_60d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_inflow\_amount\_90d** (nullable, object)  
Total amount of debit transactions into the report's account in the last 90 days. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_inflow\_amount\_90d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_inflow\_amount\_90d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_inflow\_amount\_90d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_outflow\_amount** (nullable, object)  
Total amount of credit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_outflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_outflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_outflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_outflow\_amount\_30d** (nullable, object)  
Total amount of credit transactions into the report's accounts in the last 30 days. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_outflow\_amount\_30d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_outflow\_amount\_30d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_outflow\_amount\_30d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_outflow\_amount\_60d** (nullable, object)  
Total amount of credit transactions into the report's accounts in the last 60 days. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_outflow\_amount\_60d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_outflow\_amount\_60d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_outflow\_amount\_60d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->attributes->total\_outflow\_amount\_90d** (nullable, object)  
Total amount of credit transactions into the report's accounts in the last 90 days. This field only takes into account USD transactions from the accounts.

**report->attributes->total\_outflow\_amount\_90d->amount** (number)  
Value of amount with up to 2 decimal places.

**report->attributes->total\_outflow\_amount\_90d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->attributes->total\_outflow\_amount\_90d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**warnings** (\[object\])  
If the Base Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing

**warnings->warning\_type** (string)  
The warning type, which will always be BASE\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Account-owner information is not available. TRANSACTIONS\_UNAVAILABLE: Transactions information associated with Credit and Depository accounts are unavailable. USER\_FRAUD\_ALERT: The User has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Note: when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, USER\_FRAUD\_ALERT

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "report": {
    "date_generated": "2024-07-16T01:52:42.912331716Z",
    "days_requested": 365,
    "items": [
      {
        "accounts": [
          {
            "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
            "account_insights": {
              "average_days_between_transactions": 0.15,
              "average_inflow_amount": [
                {
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01",
                  "total_amount": {
                    "amount": 1077.93,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                }
              ],
              "average_inflow_amounts": [
                {
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01",
                  "total_amount": {
                    "amount": 1077.93,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                },
                {
                  "end_date": "2024-08-31",
                  "start_date": "2024-08-01",
                  "total_amount": {
                    "amount": 1076.93,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                }
              ],
              "average_outflow_amount": [
                {
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01",
                  "total_amount": {
                    "amount": 34.95,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                }
              ],
              "average_outflow_amounts": [
                {
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01",
                  "total_amount": {
                    "amount": 34.95,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                },
                {
                  "end_date": "2024-08-31",
                  "start_date": "2024-08-01",
                  "total_amount": {
                    "amount": 0,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                }
              ],
              "days_available": 365,
              "longest_gap_between_transactions": [
                {
                  "days": 1,
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01"
                }
              ],
              "longest_gaps_between_transactions": [
                {
                  "days": 1,
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01"
                },
                {
                  "days": 2,
                  "end_date": "2024-08-31",
                  "start_date": "2024-08-01"
                }
              ],
              "most_recent_transaction_date": "2024-07-16",
              "number_of_days_no_transactions": 0,
              "number_of_inflows": [
                {
                  "count": 1,
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01"
                }
              ],
              "number_of_outflows": [
                {
                  "count": 27,
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01"
                }
              ],
              "oldest_transaction_date": "2024-07-12"
            },
            "balances": {
              "available": 5000,
              "average_balance": 4956.12,
              "average_monthly_balances": [
                {
                  "average_balance": {
                    "amount": 4956.12,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  },
                  "end_date": "2024-07-31",
                  "start_date": "2024-07-01"
                }
              ],
              "current": 5000,
              "iso_currency_code": "USD",
              "limit": null,
              "most_recent_thirty_day_average_balance": 4956.125,
              "unofficial_currency_code": null
            },
            "consumer_disputes": [],
            "days_available": 365,
            "mask": "1208",
            "metadata": {
              "start_date": "2024-01-01",
              "end_date": "2024-07-16"
            },
            "name": "Checking",
            "official_name": "Plaid checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "+1 111-555-3333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "+1 111-555-4444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "+1 111-555-5555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "checking",
            "transactions": [
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 37.07,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-12",
                "date_posted": "2024-07-12T00:00:00Z",
                "date_transacted": "2024-07-12",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Amazon",
                "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM",
                "pending": false,
                "transaction_id": "XA7ZLy8rXzt7D3j9B6LMIgv5VxyQkAhbKjzmp",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 51.61,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-12",
                "date_posted": "2024-07-12T00:00:00Z",
                "date_transacted": "2024-07-12",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Domino's",
                "original_description": "DOMINO's XXXX 111-222-3333",
                "pending": false,
                "transaction_id": "VEPeMbWqRluPVZLQX4MDUkKRw41Ljzf9gyLBW",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 7.55,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_FURNITURE_AND_HARDWARE",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-12",
                "date_posted": "2024-07-12T00:00:00Z",
                "date_transacted": "2024-07-12",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Chicago",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "IKEA",
                "original_description": "IKEA CHICAGO",
                "pending": false,
                "transaction_id": "6GQZARgvroCAE1eW5wpQT7w3oB6nvzi8DKMBa",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 12.87,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_SPORTING_GOODS",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-12",
                "date_posted": "2024-07-12T00:00:00Z",
                "date_transacted": "2024-07-12",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Redlands",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "CA",
                  "state": "CA",
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Nike",
                "original_description": "NIKE REDLANDS CA",
                "pending": false,
                "transaction_id": "DkbmlP8BZxibzADqNplKTeL8aZJVQ1c3WR95z",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 44.21,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-12",
                "date_posted": "2024-07-12T00:00:00Z",
                "date_transacted": "2024-07-12",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": null,
                "original_description": "POKE BROS * POKE BRO IL",
                "pending": false,
                "transaction_id": "RpdN7W8GmRSdjZB9Jm7ATj4M86vdnktapkrgL",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 36.82,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_DISCOUNT_STORES",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-13",
                "date_posted": "2024-07-13T00:00:00Z",
                "date_transacted": "2024-07-13",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Family Dollar",
                "original_description": "FAMILY DOLLAR",
                "pending": false,
                "transaction_id": "5AeQWvo5KLtAD9wNL68PTdAgPE7VNWf5Kye1G",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 13.27,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-13",
                "date_posted": "2024-07-13T00:00:00Z",
                "date_transacted": "2024-07-13",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Instacart",
                "original_description": "INSTACART HTTPSINSTACAR CA",
                "pending": false,
                "transaction_id": "Jjlr3MEVg1HlKbdkZj39ij5a7eg9MqtB6MWDo",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 36.03,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-13",
                "date_posted": "2024-07-13T00:00:00Z",
                "date_transacted": "2024-07-13",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": null,
                "original_description": "POKE BROS * POKE BRO IL",
                "pending": false,
                "transaction_id": "kN9KV7yAZJUMPn93KDXqsG9MrpjlyLUL6Dgl8",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 54.74,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-13",
                "date_posted": "2024-07-13T00:00:00Z",
                "date_transacted": "2024-07-13",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Whittier",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "CA",
                  "state": "CA",
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Smart & Final",
                "original_description": "POS SMART AND FINAL 111 WHITTIER CA",
                "pending": false,
                "transaction_id": "lPvrweZAMqHDar43vwWKs547kLZVEzfpogGVJ",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 37.5,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-13",
                "date_posted": "2024-07-13T00:00:00Z",
                "date_transacted": "2024-07-13",
                "iso_currency_code": "USD",
                "location": {
                  "address": "1627 N 24th St",
                  "city": "Phoenix",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": "85008",
                  "region": "AZ",
                  "state": "AZ",
                  "store_number": null,
                  "zip": "85008"
                },
                "merchant_name": "Taqueria El Guerrerense",
                "original_description": "TAQUERIA EL GUERRERO PHOENIX AZ",
                "pending": false,
                "transaction_id": "wka74WKqngiyJ3pj7dl5SbpLGQBZqyCPZRDbP",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 41.42,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-14",
                "date_posted": "2024-07-14T00:00:00Z",
                "date_transacted": "2024-07-14",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Amazon",
                "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM",
                "pending": false,
                "transaction_id": "BBGnV4RkerHjn8WVavGyiJbQ95VNDaC4M56bJ",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": -1077.93,
                "check_number": null,
                "credit_category": {
                  "detailed": "INCOME_OTHER",
                  "primary": "INCOME"
                },
                "date": "2024-07-14",
                "date_posted": "2024-07-14T00:00:00Z",
                "date_transacted": "2024-07-14",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Lyft",
                "original_description": "LYFT TRANSFER",
                "pending": false,
                "transaction_id": "3Ej78yKJlQu1Abw7xzo4U4JR6pmwzntZlbKDK",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 47.17,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-14",
                "date_posted": "2024-07-14T00:00:00Z",
                "date_transacted": "2024-07-14",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Whittier",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "CA",
                  "state": "CA",
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Smart & Final",
                "original_description": "POS SMART AND FINAL 111 WHITTIER CA",
                "pending": false,
                "transaction_id": "rMzaBpJw8jSZRJQBabKdteQBwd5EaWc7J9qem",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 12.37,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-14",
                "date_posted": "2024-07-14T00:00:00Z",
                "date_transacted": "2024-07-14",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Whittier",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "CA",
                  "state": "CA",
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Smart & Final",
                "original_description": "POS SMART AND FINAL 111 WHITTIER CA",
                "pending": false,
                "transaction_id": "zWPZjkmzynTyel89ZjExS59DV6WAaZflNBJ56",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 44.18,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-14",
                "date_posted": "2024-07-14T00:00:00Z",
                "date_transacted": "2024-07-14",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Portland",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "OR",
                  "state": "OR",
                  "store_number": "1111",
                  "zip": null
                },
                "merchant_name": "Safeway",
                "original_description": "SAFEWAY #1111 PORTLAND OR            111111",
                "pending": false,
                "transaction_id": "K7qzx1nP8ptqgwaRMbxyI86XrqADMluRpkWx5",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 45.37,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-14",
                "date_posted": "2024-07-14T00:00:00Z",
                "date_transacted": "2024-07-14",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Uber Eats",
                "original_description": "UBER EATS",
                "pending": false,
                "transaction_id": "qZrdzLRAgNHo5peMdD9xIzELl3a1NvcgrPAzL",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 15.22,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Amazon",
                "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM",
                "pending": false,
                "transaction_id": "NZzx4oRPkAHzyRekpG4PTZkWnBPqEyiy6pB1M",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 26.33,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Domino's",
                "original_description": "DOMINO's XXXX 111-222-3333",
                "pending": false,
                "transaction_id": "x84eNArKbESz8Woden6LT3nvyogeJXc64Pp35",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 39.8,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_DISCOUNT_STORES",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Family Dollar",
                "original_description": "FAMILY DOLLAR",
                "pending": false,
                "transaction_id": "dzWnyxwZ4GHlZPGgrNyxiMG7qd5jDgCJEz5jL",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 45.06,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Instacart",
                "original_description": "INSTACART HTTPSINSTACAR CA",
                "pending": false,
                "transaction_id": "4W7eE9rZqMToDArbPeLNIREoKpdgBMcJbVNQD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 34.91,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Whittier",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "CA",
                  "state": "CA",
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Smart & Final",
                "original_description": "POS SMART AND FINAL 111 WHITTIER CA",
                "pending": false,
                "transaction_id": "j4yqDjb7QwS7woGzqrgDIEG1NaQVZwf6Wmz3D",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 49.78,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Portland",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "OR",
                  "state": "OR",
                  "store_number": "1111",
                  "zip": null
                },
                "merchant_name": "Safeway",
                "original_description": "SAFEWAY #1111 PORTLAND OR            111111",
                "pending": false,
                "transaction_id": "aqgWnze7xoHd6DQwLPnzT5dgPKjB1NfZ5JlBy",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 54.24,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-15",
                "date_posted": "2024-07-15T00:00:00Z",
                "date_transacted": "2024-07-15",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": "Portland",
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": "OR",
                  "state": "OR",
                  "store_number": "1111",
                  "zip": null
                },
                "merchant_name": "Safeway",
                "original_description": "SAFEWAY #1111 PORTLAND OR            111111",
                "pending": false,
                "transaction_id": "P13aP8b7nmS3WQoxg1PMsdvMK679RNfo65B4G",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 41.79,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-16",
                "date_posted": "2024-07-16T00:00:00Z",
                "date_transacted": "2024-07-16",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Amazon",
                "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM",
                "pending": false,
                "transaction_id": "7nZMG6pXz8SADylMqzx7TraE4qjJm7udJyAGm",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 33.86,
                "check_number": null,
                "credit_category": {
                  "detailed": "FOOD_RETAIL_GROCERIES",
                  "primary": "FOOD_RETAIL"
                },
                "date": "2024-07-16",
                "date_posted": "2024-07-16T00:00:00Z",
                "date_transacted": "2024-07-16",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "Instacart",
                "original_description": "INSTACART HTTPSINSTACAR CA",
                "pending": false,
                "transaction_id": "MQr3ap7PWEIrQG7bLdaNsxyBV7g1KqCL6pwoy",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 27.08,
                "check_number": null,
                "credit_category": {
                  "detailed": "DINING_DINING",
                  "primary": "DINING"
                },
                "date": "2024-07-16",
                "date_posted": "2024-07-16T00:00:00Z",
                "date_transacted": "2024-07-16",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": null,
                "original_description": "POKE BROS * POKE BRO IL",
                "pending": false,
                "transaction_id": "eBAk9dvwNbHPZpr8W69dU3rekJz47Kcr9BRwl",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 25.94,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_FURNITURE_AND_HARDWARE",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-16",
                "date_posted": "2024-07-16T00:00:00Z",
                "date_transacted": "2024-07-16",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": "The Home Depot",
                "original_description": "THE HOME DEPOT",
                "pending": false,
                "transaction_id": "QLx4jEJZb9SxRm7aWbjAio3LrgZ5vPswm64dE",
                "unofficial_currency_code": null
              },
              {
                "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E",
                "account_owner": null,
                "amount": 27.57,
                "check_number": null,
                "credit_category": {
                  "detailed": "GENERAL_MERCHANDISE_OTHER_GENERAL_MERCHANDISE",
                  "primary": "GENERAL_MERCHANDISE"
                },
                "date": "2024-07-16",
                "date_posted": "2024-07-16T00:00:00Z",
                "date_transacted": "2024-07-16",
                "iso_currency_code": "USD",
                "location": {
                  "address": null,
                  "city": null,
                  "country": null,
                  "lat": null,
                  "lon": null,
                  "postal_code": null,
                  "region": null,
                  "state": null,
                  "store_number": null,
                  "zip": null
                },
                "merchant_name": null,
                "original_description": "The Press Club",
                "pending": false,
                "transaction_id": "ZnQ1ovqBldSQ6GzRbroAHLdQP68BrKceqmAjX",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2024-07-16T01:52:42.912331716Z",
        "institution_id": "ins_109512",
        "institution_name": "Houndstooth Bank",
        "item_id": "NZzx4oRPkAHzyRekpG4PTZkDNkQW93tWnyGeA"
      }
    ],
    "report_id": "f3bb434f-1c9b-4ef2-b76c-3d1fd08156ec"
  },
  "warnings": [],
  "request_id": "FibfL8t3s71KJnj"
}
```

\=\*=\*=\*=

#### /cra/check\_report/income\_insights/get 

#### Retrieve cash flow information from your user's banks 

This endpoint allows you to retrieve the Income Insights report for your user. You should call this endpoint after you've received a `CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the base report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
try {
  const response = await client.craCheckReportIncomeInsightsGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  });
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**report** (object)  
The Check Income Insights Report for an end user.

**report->report\_id** (string)  
The unique identifier associated with the Check Income Insights Report.

**report->generated\_time** (string)  
The time when the Check Income Insights Report was generated. Format: date-time

**report->days\_requested** (integer)  
The number of days requested by the customer for the Check Income Insights Report.

**report->client\_report\_id** (nullable, string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**report->items** (\[object\])  
The list of Items in the report along with the associated metadata about the Item.

**report->items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**report->items->bank\_income\_accounts** (\[object\])  
The Item's accounts that have bank income data.

**report->items->bank\_income\_accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->items->bank\_income\_accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**report->items->bank\_income\_accounts->metadata** (object)  
An object containing metadata about the extracted account.

**report->items->bank\_income\_accounts->metadata->start\_date** (nullable, string)  
The date of the earliest extracted transaction, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**report->items->bank\_income\_accounts->metadata->end\_date** (nullable, string)  
The date of the most recent extracted transaction, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**report->items->bank\_income\_accounts->name** (string)  
The name of the bank account.

**report->items->bank\_income\_accounts->official\_name** (nullable, string)  
The official name of the bank account.

**report->items->bank\_income\_accounts->subtype** (string)  
Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas. Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all

**report->items->bank\_income\_accounts->type** (string)  
The account type. This will always be depository. Possible values: depository

**report->items->bank\_income\_sources** (\[object\])  
The income sources for this Item. Each entry in the array is a single income source.

**report->items->bank\_income\_sources->account\_id** (string)  
The account ID with which this income source is associated.

**report->items->bank\_income\_sources->income\_source\_id** (string)  
A unique identifier for an income source. If the report is regenerated and a new report\_id is created, the new report will have a new set of income\_source\_ids.

**report->items->bank\_income\_sources->income\_description** (string)  
The most common name or original description for the underlying income transactions.

**report->items->bank\_income\_sources->income\_category** (string)  
The income category. BANK\_INTEREST: Interest earned from a bank account. BENEFIT\_OTHER: Government benefits other than retirement, unemployment, child support, or disability. Currently used only in the UK, to represent benefits such as Cost of Living Payments. CASH: Deprecated and used only for existing legacy implementations. Has been replaced by CASH\_DEPOSIT and TRANSFER\_FROM\_APPLICATION. CASH\_DEPOSIT: A cash or check deposit. CHILD\_SUPPORT: Child support payments received. GIG\_ECONOMY: Income earned as a gig economy worker, e.g. driving for Uber, Lyft, Postmates, DoorDash, etc. LONG\_TERM\_DISABILITY: Disability payments, including Social Security disability benefits. OTHER: Income that could not be categorized as any other income category. MILITARY: Veterans benefits. Income earned as salary for serving in the military (e.g. through DFAS) will be classified as SALARY rather than MILITARY. RENTAL: Income earned from a rental property. Income may be identified as rental when the payment is received through a rental platform, e.g. Airbnb; rent paid directly by the tenant to the property owner (e.g. via cash, check, or ACH) will typically not be classified as rental income. RETIREMENT: Payments from private retirement systems, pensions, and government retirement programs, including Social Security retirement benefits. SALARY: Payment from an employer to an earner or other form of permanent employment. TAX\_REFUND: A tax refund. TRANSFER\_FROM\_APPLICATION: Deposits from a money transfer app, such as Venmo, Cash App, or Zelle. UNEMPLOYMENT: Unemployment benefits. In the UK, includes certain low-income benefits such as the Universal Credit. Possible values: SALARY, UNEMPLOYMENT, CASH, GIG\_ECONOMY, RENTAL, CHILD\_SUPPORT, MILITARY, RETIREMENT, LONG\_TERM\_DISABILITY, BANK\_INTEREST, CASH\_DEPOSIT, TRANSFER\_FROM\_APPLICATION, TAX\_REFUND, BENEFIT\_OTHER, OTHER

**report->items->bank\_income\_sources->start\_date** (string)  
Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->bank\_income\_sources->end\_date** (string)  
Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->bank\_income\_sources->pay\_frequency** (string)  
The income pay frequency. Possible values: WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, DAILY, UNKNOWN

**report->items->bank\_income\_sources->total\_amount** (number)  
Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.

**report->items->bank\_income\_sources->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->bank\_income\_sources->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->bank\_income\_sources->transaction\_count** (integer)  
Number of transactions for the income source within the start and end date.

**report->items->bank\_income\_sources->next\_payment\_date** (nullable, string)  
The expected date of the end user’s next paycheck for the income source. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->bank\_income\_sources->historical\_average\_monthly\_gross\_income** (nullable, number)  
An estimate of the average gross monthly income based on the historical net amount and income category for the income source(s).

**report->items->bank\_income\_sources->historical\_average\_monthly\_income** (nullable, number)  
The average monthly net income amount estimated based on the historical data for the income source(s).

**report->items->bank\_income\_sources->forecasted\_average\_monthly\_income** (nullable, number)  
The predicted average monthly net income amount for the income source(s).

**report->items->bank\_income\_sources->forecasted\_average\_monthly\_income\_prediction\_intervals** (\[object\])  
The prediction interval(s) for the forecasted average monthly income.

**report->items->bank\_income\_sources->forecasted\_average\_monthly\_income\_prediction\_intervals->lower\_bound** (nullable, number)  
The lower bound of the predicted attribute for the given probability.

**report->items->bank\_income\_sources->forecasted\_average\_monthly\_income\_prediction\_intervals->upper\_bound** (nullable, number)  
The upper bound of the predicted attribute for the given probability.

**report->items->bank\_income\_sources->forecasted\_average\_monthly\_income\_prediction\_intervals->probability** (nullable, number)  
The probability of the actual value of the attribute falling within the upper and lower bound. This is a percentage represented as a value between 0 and 1.

**report->items->bank\_income\_sources->employer** (object)  
The object containing employer data.

**report->items->bank\_income\_sources->employer->name** (nullable, string)  
The name of the employer.

**report->items->bank\_income\_sources->historical\_summary** (\[object\])  
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.

number

**report->items->bank\_income\_sources->historical\_summary->total\_amounts** (\[object\])  
Value of amount with up to 2 decimal places.

**report->items->bank\_income\_sources->historical\_summary->total\_amounts->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->bank\_income\_sources->historical\_summary->total\_amounts->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->bank\_income\_sources->historical\_summary->start\_date** (string)  
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->bank\_income\_sources->historical\_summary->end\_date** (string)  
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

string

**report->items->bank\_income\_sources->historical\_summary->transactions** (\[object\])  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->items->bank\_income\_sources->historical\_summary->transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.

**report->items->bank\_income\_sources->historical\_summary->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->items->bank\_income\_sources->historical\_summary->transactions->name** (deprecated, string)  
The merchant name or transaction description. This is a legacy field that is no longer maintained. For merchant name, use the merchant\_name field; for description, use the original\_description field.

**report->items->bank\_income\_sources->historical\_summary->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**report->items->bank\_income\_sources->historical\_summary->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->items->bank\_income\_sources->historical\_summary->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**report->items->bank\_income\_sources->historical\_summary->transactions->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->items->bank\_income\_sources->historical\_summary->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->items->bank\_income\_sources->historical\_summary->transactions->bonus\_type** (nullable, string)  
The type of bonus that this transaction represents, if it is a bonus. BONUS\_INCLUDED: Bonus is included in this transaction along with the normal pay BONUS\_ONLY: This transaction is a standalone bonus Possible values: BONUS\_INCLUDED, BONUS\_ONLY, null

**report->items->last\_updated\_time** (string)  
The time when this Item's data was last retrieved from the financial institution. Format: date-time

**report->items->institution\_id** (string)  
The unique identifier of the institution associated with the Item.

**report->items->institution\_name** (string)  
The name of the institution associated with the Item.

**report->bank\_income\_summary** (object)  
Summary for income across all income sources and items (max history of 730 days).

**report->bank\_income\_summary->total\_amounts** (\[object\])  
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This can contain multiple amounts, with each amount denominated in one unique currency.

**report->bank\_income\_summary->total\_amounts->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->total\_amounts->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->total\_amounts->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->start\_date** (string)  
The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->bank\_income\_summary->end\_date** (string)  
The latest date in which all income sources identified by Plaid appear in the user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->bank\_income\_summary->income\_sources\_count** (integer)  
Number of income sources per end user.

**report->bank\_income\_summary->income\_categories\_count** (integer)  
Number of income categories per end user.

**report->bank\_income\_summary->income\_transactions\_count** (integer)  
Number of income transactions per end user.

**report->bank\_income\_summary->historical\_average\_monthly\_gross\_income** (\[object\])  
An estimate of the average gross monthly income based on the historical net amount and income category for the income source(s). The average monthly income is calculated based on the lifetime of the income stream, rather than the entire historical period included in the scope of the report.

**report->bank\_income\_summary->historical\_average\_monthly\_gross\_income->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->historical\_average\_monthly\_gross\_income->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->historical\_average\_monthly\_gross\_income->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->historical\_average\_monthly\_income** (\[object\])  
The average monthly income amount estimated based on the historical data for the income source(s). The average monthly income is calculated based on the lifetime of the income stream, rather than the entire historical period included in the scope of the report.

**report->bank\_income\_summary->historical\_average\_monthly\_income->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->historical\_average\_monthly\_income->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->historical\_average\_monthly\_income->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->forecasted\_average\_monthly\_income** (\[object\])  
The predicted average monthly income amount for the income source(s).

**report->bank\_income\_summary->forecasted\_average\_monthly\_income->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->forecasted\_average\_monthly\_income->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->forecasted\_average\_monthly\_income->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->historical\_annual\_gross\_income** (\[object\])  
An estimate of the annual gross income for the income source, calculated by multiplying the historical\_average\_monthly\_gross\_income by 12.

**report->bank\_income\_summary->historical\_annual\_gross\_income->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->historical\_annual\_gross\_income->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->historical\_annual\_gross\_income->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->historical\_annual\_income** (\[object\])  
An estimate of the annual net income for the income source, calculated by multiplying the historical\_average\_monthly\_income by 12.

**report->bank\_income\_summary->historical\_annual\_income->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->historical\_annual\_income->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->historical\_annual\_income->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->forecasted\_annual\_income** (\[object\])  
The predicted average annual income amount for the income source(s).

**report->bank\_income\_summary->forecasted\_annual\_income->amount** (number)  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->forecasted\_annual\_income->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->forecasted\_annual\_income->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->historical\_summary** (\[object\])  
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.

number

**report->bank\_income\_summary->historical\_summary->total\_amounts** (\[object\])  
Value of amount with up to 2 decimal places.

**report->bank\_income\_summary->historical\_summary->total\_amounts->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->historical\_summary->total\_amounts->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->historical\_summary->start\_date** (string)  
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->bank\_income\_summary->historical\_summary->end\_date** (string)  
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

string

**report->bank\_income\_summary->historical\_summary->transactions** (\[object\])  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->bank\_income\_summary->historical\_summary->transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.

**report->bank\_income\_summary->historical\_summary->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->bank\_income\_summary->historical\_summary->transactions->name** (deprecated, string)  
The merchant name or transaction description. This is a legacy field that is no longer maintained. For merchant name, use the merchant\_name field; for description, use the original\_description field.

**report->bank\_income\_summary->historical\_summary->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**report->bank\_income\_summary->historical\_summary->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->bank\_income\_summary->historical\_summary->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**report->bank\_income\_summary->historical\_summary->transactions->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->bank\_income\_summary->historical\_summary->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->bank\_income\_summary->historical\_summary->transactions->bonus\_type** (nullable, string)  
The type of bonus that this transaction represents, if it is a bonus. BONUS\_INCLUDED: Bonus is included in this transaction along with the normal pay BONUS\_ONLY: This transaction is a standalone bonus Possible values: BONUS\_INCLUDED, BONUS\_ONLY, null

**report->warnings** (\[object\])  
If data from the report was unable to be retrieved, the warnings object will contain information about the error that caused the data to be incomplete.

**report->warnings->warning\_type** (string)  
The warning type which will always be BANK\_INCOME\_WARNING. Possible values: BANK\_INCOME\_WARNING

**report->warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Unable to extract identity for the Item TRANSACTIONS\_UNAVAILABLE: Unable to extract transactions for the Item REPORT\_DELETED: Report deleted due to customer or consumer request DATA\_UNAVAILABLE: No relevant data was found for the Item Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, REPORT\_DELETED, DATA\_UNAVAILABLE

**report->warnings->cause** (object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**report->warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INTERNAL\_SERVER\_ERROR, INSUFFICIENT\_CREDENTIALS, ITEM\_LOCKED, USER\_SETUP\_REQUIRED, COUNTRY\_NOT\_SUPPORTED, INSTITUTION\_DOWN, INSTITUTION\_NO\_LONGER\_SUPPORTED, INSTITUTION\_NOT\_RESPONDING, INVALID\_CREDENTIALS, INVALID\_MFA, INVALID\_SEND\_METHOD, ITEM\_LOGIN\_REQUIRED, MFA\_NOT\_SUPPORTED, NO\_ACCOUNTS, ITEM\_NOT\_SUPPORTED, ACCESS\_NOT\_GRANTED

**report->warnings->cause->error\_code** (string)  
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error\_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred.

**report->warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**report->warnings->cause->display\_message** (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 identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**warnings** (\[object\])  
If the Income Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing

**warnings->warning\_type** (string)  
The warning type, which will always be CHECK\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Account-owner information is not available. TRANSACTIONS\_UNAVAILABLE: Transactions information associated with Credit and Depository accounts are unavailable. USER\_FRAUD\_ALERT: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, USER\_FRAUD\_ALERT

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

```json
{
  "request_id": "LhQf0THi8SH1yJm",
  "report": {
    "report_id": "bbfc5174-5433-4648-8d93-9fec6a0c0966",
    "generated_time": "2022-01-31T22:47:53Z",
    "days_requested": 365,
    "items": [
      {
        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7",
        "last_updated_time": "2022-01-31T22:47:53Z",
        "institution_id": "ins_0",
        "institution_name": "Plaid Bank",
        "bank_income_accounts": [
          {
            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
            "mask": "8888",
            "metadata": {
              "start_date": "2024-01-01",
              "end_date": "2024-07-16"
            },
            "name": "Plaid Checking Account",
            "official_name": "Plaid Checking Account",
            "type": "depository",
            "subtype": "checking",
            "owners": []
          }
        ],
        "bank_income_sources": [
          {
            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
            "income_source_id": "f17efbdd-caab-4278-8ece-963511cd3d51",
            "income_description": "PLAID_INC_DIRECT_DEP_PPD",
            "income_category": "SALARY",
            "start_date": "2021-11-15",
            "end_date": "2022-01-15",
            "pay_frequency": "MONTHLY",
            "total_amount": 300,
            "iso_currency_code": "USD",
            "unofficial_currency_code": null,
            "transaction_count": 1,
            "next_payment_date": "2022-12-15",
            "historical_average_monthly_gross_income": 390,
            "historical_average_monthly_income": 300,
            "forecasted_average_monthly_income": 300,
            "forecasted_average_monthly_income_prediction_intervals": [
              {
                "lower_bound": 200,
                "upper_bound": 400,
                "probability": 0.8
              }
            ],
            "employer": {
              "name": "Plaid Inc"
            },
            "historical_summary": [
              {
                "start_date": "2021-11-02",
                "end_date": "2021-11-30",
                "total_amounts": [
                  {
                    "amount": 100,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "transactions": [
                  {
                    "transaction_id": "aH5klwqG3B19OMT7D6F24Syv8pdnJXmtZoKQ5",
                    "amount": 100,
                    "bonus_type": null,
                    "date": "2021-11-15",
                    "name": "PLAID_INC_DIRECT_DEP_PPD",
                    "original_description": "PLAID_INC_DIRECT_DEP_PPD 123A",
                    "pending": false,
                    "check_number": null,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ]
              },
              {
                "start_date": "2021-12-01",
                "end_date": "2021-12-31",
                "total_amounts": [
                  {
                    "amount": 100,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "transactions": [
                  {
                    "transaction_id": "mN3rQ5iH8BC41T6UjKL9oD2vWJpZqXFomGwY1",
                    "amount": 100,
                    "bonus_type": null,
                    "date": "2021-12-15",
                    "name": "PLAID_INC_DIRECT_DEP_PPD",
                    "original_description": "PLAID_INC_DIRECT_DEP_PPD 123B",
                    "pending": false,
                    "check_number": null,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ]
              },
              {
                "start_date": "2022-01-01",
                "end_date": "2022-01-31",
                "total_amounts": [
                  {
                    "amount": 100,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "transactions": [
                  {
                    "transaction_id": "zK9lDoR8uBH51PNQ3W4T6Mjy2VFXpGtJwsL4",
                    "amount": 100,
                    "bonus_type": null,
                    "date": "2022-01-31",
                    "name": "PLAID_INC_DIRECT_DEP_PPD",
                    "original_description": "PLAID_INC_DIRECT_DEP_PPD 123C",
                    "pending": false,
                    "check_number": null,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "bank_income_summary": {
      "total_amounts": [
        {
          "amount": 300,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "start_date": "2021-11-15",
      "end_date": "2022-01-15",
      "income_sources_count": 1,
      "income_categories_count": 1,
      "income_transactions_count": 1,
      "historical_average_monthly_gross_income": [
        {
          "amount": 390,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "historical_average_monthly_income": [
        {
          "amount": 300,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "forecasted_average_monthly_income": [
        {
          "amount": 300,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "historical_annual_gross_income": [
        {
          "amount": 4680,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "historical_annual_income": [
        {
          "amount": 3600,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "forecasted_annual_income": [
        {
          "amount": 3600,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "historical_summary": [
        {
          "start_date": "2021-11-02",
          "end_date": "2021-11-30",
          "total_amounts": [
            {
              "amount": 100,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ],
          "transactions": [
            {
              "transaction_id": "aH5klwqG3B19OMT7D6F24Syv8pdnJXmtZoKQ5",
              "amount": 100,
              "bonus_type": null,
              "date": "2021-11-15",
              "name": "PLAID_INC_DIRECT_DEP_PPD",
              "original_description": "PLAID_INC_DIRECT_DEP_PPD 123A",
              "pending": false,
              "check_number": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ]
        },
        {
          "start_date": "2021-12-01",
          "end_date": "2021-12-31",
          "total_amounts": [
            {
              "amount": 100,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ],
          "transactions": [
            {
              "transaction_id": "mN3rQ5iH8BC41T6UjKL9oD2vWJpZqXFomGwY1",
              "amount": 100,
              "bonus_type": null,
              "date": "2021-12-15",
              "name": "PLAID_INC_DIRECT_DEP_PPD",
              "original_description": "PLAID_INC_DIRECT_DEP_PPD 123B",
              "pending": false,
              "check_number": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ]
        },
        {
          "start_date": "2022-01-01",
          "end_date": "2022-01-31",
          "total_amounts": [
            {
              "amount": 100,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ],
          "transactions": [
            {
              "transaction_id": "zK9lDoR8uBH51PNQ3W4T6Mjy2VFXpGtJwsL4",
              "amount": 100,
              "bonus_type": null,
              "date": "2022-01-31",
              "name": "PLAID_INC_DIRECT_DEP_PPD",
              "original_description": "PLAID_INC_DIRECT_DEP_PPD 123C",
              "pending": false,
              "check_number": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ]
        }
      ],
      "warnings": []
    }
  }
}
```

\=\*=\*=\*=

#### /cra/check\_report/network\_insights/get 

#### Retrieve network attributes for the user 

This endpoint allows you to retrieve the Network Insights product for your user. You should call this endpoint after you've received the `CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .  
If you did not initialize Link with the `cra_network_attributes` product or have generated a report using [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , we will generate the attributes when you call this endpoint.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
try {
  const response = await client.craCheckReportNetworkInsightsGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  });
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**report** (object)  
Contains data for the CRA Network Attributes Report.

**report->report\_id** (string)  
The unique identifier associated with the Network Attributes report object.

**report->generated\_time** (string)  
The time when the Network Attributes Report was generated. Format: date-time

**report->network\_attributes** (object)  
A map of network attributes, where the key is a string, and the value is a float, int, or boolean.

**report->items** (\[object\])  
The Items the end user connected in Link.

**report->items->institution\_id** (string)  
The ID for the institution the user linked.

**report->items->institution\_name** (string)  
The name of the institution the user linked.

**report->items->item\_id** (string)  
The identifier for the Item.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**warnings** (\[object\])  
If the Network Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing

**warnings->warning\_type** (string)  
The warning type, which will always be CHECK\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Account-owner information is not available. TRANSACTIONS\_UNAVAILABLE: Transactions information associated with Credit and Depository accounts are unavailable. USER\_FRAUD\_ALERT: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, USER\_FRAUD\_ALERT

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

```json
{
  "request_id": "LhQf0THi8SH1yJm",
  "report": {
    "report_id": "ee093cb0-e3f2-42d1-9dbc-8d8408964194",
    "generated_time": "2022-01-31T22:47:53Z",
    "network_attributes": {
      "plaid_conn_user_lifetime__lending_count": 5,
      "plaid_conn_user_lifetime__personal_lending_flag": true,
      "plaid_conn_user_lifetime__cash_advance_primary_count": 0
    },
    "items": [
      {
        "institution_id": "ins_0",
        "institution_name": "Plaid Bank",
        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7"
      }
    ]
  }
}
```

\=\*=\*=\*=

#### /cra/check\_report/partner\_insights/get 

#### Retrieve cash flow insights from partners 

This endpoint allows you to retrieve the Partner Insights report for your user. You should call this endpoint after you've received the `CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the base report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .  
If you did not initialize Link with the `credit_partner_insights` product or have generated a report using [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , we will call our partners to generate the insights when you call this endpoint. In this case, you may optionally provide parameters under `options` to configure which insights you want to receive.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

**partner\_insights** (object)  
Defines configuration to generate Partner Insights

**partner\_insights->prism\_versions** (object)  
The versions of Prism products to evaluate

**partner\_insights->prism\_versions->firstdetect** (string)  
The version of Prism FirstDetect. If not specified, will default to v3. Possible values: 3, null

**partner\_insights->prism\_versions->detect** (string)  
The version of Prism Detect Possible values: 4, null

**partner\_insights->prism\_versions->cashscore** (string)  
The version of Prism CashScore. If not specified, will default to v3. Possible values: 4, 3, null

**partner\_insights->prism\_versions->extend** (string)  
The version of Prism Extend Possible values: 4, null

**partner\_insights->prism\_versions->insights** (string)  
The version of Prism Insights. If not specified, will default to v3. Possible values: 4, 3, null

**options** (deprecated, object)  
Deprecated, specify partner\_insights.prism\_versions instead.

**options->prism\_products** (deprecated, \[string\])  
The specific Prism Data products to return. If none are passed in, then all products will be returned. Possible values: insights, scores

**options->prism\_versions** (deprecated, object)  
Deprecated, use partner\_insights.prism\_versions instead.

**options->prism\_versions->firstdetect** (string)  
The version of Prism FirstDetect. If not specified, will default to v3. Possible values: 3, null

**options->prism\_versions->detect** (string)  
The version of Prism Detect Possible values: 4, null

**options->prism\_versions->cashscore** (string)  
The version of Prism CashScore. If not specified, will default to v3. Possible values: 4, 3, null

**options->prism\_versions->extend** (string)  
The version of Prism Extend Possible values: 4, null

**options->prism\_versions->insights** (string)  
The version of Prism Insights. If not specified, will default to v3. Possible values: 4, 3, null

```javascript
try {
  const response = await client.craCheckReportPartnerInsightsGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  });
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**report** (object)  
The Partner Insights report of the bank data for an end user.

**report->report\_id** (string)  
A unique identifier associated with the Partner Insights object.

**report->generated\_time** (string)  
The time when the Partner Insights report was generated. Format: date-time

**report->client\_report\_id** (nullable, string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**report->prism** (object)  
The Prism Data insights for the user.

**report->prism->insights** (nullable, object)  
The data from the Insights product returned by Prism Data.

**report->prism->insights->version** (integer)  
The version of Prism Data's insights model used.

**report->prism->insights->result** (object)  
The Insights Result object is a map of cash flow attributes, where the key is a string, and the value is a float or string.

**report->prism->insights->error\_reason** (string)  
The error returned by Prism for this product.

**report->prism->cash\_score** (nullable, object)  
The data from the CashScore® product returned by Prism Data.

**report->prism->cash\_score->version** (deprecated, integer)  
The version of Prism Data's cash score model used. This field is deprecated in favor of model\_version.

**report->prism->cash\_score->model\_version** (string)  
The version of Prism Data's cash score model used.

**report->prism->cash\_score->score** (nullable, integer)  
The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk.

**report->prism->cash\_score->reason\_codes** (\[string\])  
The reasons for an individual having risk according to the cash score.

**report->prism->cash\_score->metadata** (object)  
An object containing metadata about the provided transactions.

**report->prism->cash\_score->metadata->max\_age** (nullable, integer)  
Number of days since the oldest transaction.

**report->prism->cash\_score->metadata->min\_age** (nullable, integer)  
Number of days since the latest transaction.

**report->prism->cash\_score->metadata->min\_age\_credit** (nullable, integer)  
Number of days since the latest credit transaction.

**report->prism->cash\_score->metadata->min\_age\_debit** (nullable, integer)  
Number of days since the latest debit transaction.

**report->prism->cash\_score->metadata->max\_age\_debit** (nullable, integer)  
Number of days since the oldest debit transaction.

**report->prism->cash\_score->metadata->max\_age\_credit** (nullable, integer)  
Number of days since the oldest credit transaction.

**report->prism->cash\_score->metadata->num\_trxn\_credit** (nullable, integer)  
Number of credit transactions.

**report->prism->cash\_score->metadata->num\_trxn\_debit** (nullable, integer)  
Number of debit transactions.

**report->prism->cash\_score->metadata->l1m\_credit\_value\_cnt** (nullable, integer)  
Number of credit transactions in the last 30 days.

**report->prism->cash\_score->metadata->l1m\_debit\_value\_cnt** (nullable, integer)  
Number of debit transactions in the last 30 days.

**report->prism->cash\_score->error\_reason** (string)  
The error returned by Prism for this product.

**report->prism->extend** (nullable, object)  
The data from the CashScore® Extend product returned by Prism Data.

**report->prism->extend->model\_version** (string)  
The version of Prism Data's CashScore® Extend model used.

**report->prism->extend->score** (nullable, integer)  
The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk.

**report->prism->extend->reason\_codes** (\[string\])  
The reasons for an individual having risk according to the CashScore® Extend score.

**report->prism->extend->metadata** (object)  
An object containing metadata about the provided transactions.

**report->prism->extend->metadata->max\_age** (nullable, integer)  
Number of days since the oldest transaction.

**report->prism->extend->metadata->min\_age** (nullable, integer)  
Number of days since the latest transaction.

**report->prism->extend->metadata->min\_age\_credit** (nullable, integer)  
Number of days since the latest credit transaction.

**report->prism->extend->metadata->min\_age\_debit** (nullable, integer)  
Number of days since the latest debit transaction.

**report->prism->extend->metadata->max\_age\_debit** (nullable, integer)  
Number of days since the oldest debit transaction.

**report->prism->extend->metadata->max\_age\_credit** (nullable, integer)  
Number of days since the oldest credit transaction.

**report->prism->extend->metadata->num\_trxn\_credit** (nullable, integer)  
Number of credit transactions.

**report->prism->extend->metadata->num\_trxn\_debit** (nullable, integer)  
Number of debit transactions.

**report->prism->extend->metadata->l1m\_credit\_value\_cnt** (nullable, integer)  
Number of credit transactions in the last 30 days.

**report->prism->extend->metadata->l1m\_debit\_value\_cnt** (nullable, integer)  
Number of debit transactions in the last 30 days.

**report->prism->extend->error\_reason** (string)  
The error returned by Prism for this product.

**report->prism->first\_detect** (nullable, object)  
The data from the FirstDetect product returned by Prism Data.

**report->prism->first\_detect->version** (deprecated, integer)  
The version of Prism Data's FirstDetect model used. This field is deprecated in favor of model\_version.

**report->prism->first\_detect->model\_version** (string)  
The version of Prism Data's FirstDetect model used.

**report->prism->first\_detect->score** (nullable, integer)  
The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk.

**report->prism->first\_detect->reason\_codes** (\[string\])  
The reasons for an individual having risk according to the FirstDetect score.

**report->prism->first\_detect->metadata** (object)  
An object containing metadata about the provided transactions.

**report->prism->first\_detect->metadata->max\_age** (nullable, integer)  
Number of days since the oldest transaction.

**report->prism->first\_detect->metadata->min\_age** (nullable, integer)  
Number of days since the latest transaction.

**report->prism->first\_detect->metadata->min\_age\_credit** (nullable, integer)  
Number of days since the latest credit transaction.

**report->prism->first\_detect->metadata->min\_age\_debit** (nullable, integer)  
Number of days since the latest debit transaction.

**report->prism->first\_detect->metadata->max\_age\_debit** (nullable, integer)  
Number of days since the oldest debit transaction.

**report->prism->first\_detect->metadata->max\_age\_credit** (nullable, integer)  
Number of days since the oldest credit transaction.

**report->prism->first\_detect->metadata->num\_trxn\_credit** (nullable, integer)  
Number of credit transactions.

**report->prism->first\_detect->metadata->num\_trxn\_debit** (nullable, integer)  
Number of debit transactions.

**report->prism->first\_detect->metadata->l1m\_credit\_value\_cnt** (nullable, integer)  
Number of credit transactions in the last 30 days.

**report->prism->first\_detect->metadata->l1m\_debit\_value\_cnt** (nullable, integer)  
Number of debit transactions in the last 30 days.

**report->prism->first\_detect->error\_reason** (string)  
The error returned by Prism for this product.

**report->prism->detect** (nullable, object)  
The data from the CashScore® Detect product returned by Prism Data.

**report->prism->detect->model\_version** (string)  
The version of Prism Data's CashScore® Detect model used.

**report->prism->detect->score** (nullable, integer)  
The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk.

**report->prism->detect->reason\_codes** (\[string\])  
The reasons for an individual having risk according to the CashScore® Detect score.

**report->prism->detect->metadata** (object)  
An object containing metadata about the provided transactions.

**report->prism->detect->metadata->max\_age** (nullable, integer)  
Number of days since the oldest transaction.

**report->prism->detect->metadata->min\_age** (nullable, integer)  
Number of days since the latest transaction.

**report->prism->detect->metadata->min\_age\_credit** (nullable, integer)  
Number of days since the latest credit transaction.

**report->prism->detect->metadata->min\_age\_debit** (nullable, integer)  
Number of days since the latest debit transaction.

**report->prism->detect->metadata->max\_age\_debit** (nullable, integer)  
Number of days since the oldest debit transaction.

**report->prism->detect->metadata->max\_age\_credit** (nullable, integer)  
Number of days since the oldest credit transaction.

**report->prism->detect->metadata->num\_trxn\_credit** (nullable, integer)  
Number of credit transactions.

**report->prism->detect->metadata->num\_trxn\_debit** (nullable, integer)  
Number of debit transactions.

**report->prism->detect->metadata->l1m\_credit\_value\_cnt** (nullable, integer)  
Number of credit transactions in the last 30 days.

**report->prism->detect->metadata->l1m\_debit\_value\_cnt** (nullable, integer)  
Number of debit transactions in the last 30 days.

**report->prism->detect->error\_reason** (string)  
The error returned by Prism for this product.

**report->prism->status** (string)  
Details on whether the Prism Data attributes succeeded or failed to be generated.

**report->items** (\[object\])  
The list of Items used in the report along with the associated metadata about the Item.

**report->items->institution\_id** (string)  
The ID for the institution that the user linked.

**report->items->institution\_name** (string)  
The name of the institution the user linked.

**report->items->item\_id** (string)  
The identifier for the item.

**report->items->accounts** (\[object\])  
A list of accounts in the item

**report->items->accounts->account\_id** (string)  
Plaid's unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->items->accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**report->items->accounts->metadata** (object)  
An object containing metadata about the extracted account.

**report->items->accounts->metadata->start\_date** (nullable, string)  
The date of the earliest extracted transaction, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**report->items->accounts->metadata->end\_date** (nullable, string)  
The date of the most recent extracted transaction, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**report->items->accounts->name** (string)  
The name of the account

**report->items->accounts->official\_name** (nullable, string)  
The official name of the bank account.

**report->items->accounts->subtype** (string)  
Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas. Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all

**report->items->accounts->type** (string)  
The account type. This will always be depository. Possible values: depository

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**warnings** (\[object\])  
If the Partner Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing

**warnings->warning\_type** (string)  
The warning type, which will always be CHECK\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Account-owner information is not available. TRANSACTIONS\_UNAVAILABLE: Transactions information associated with Credit and Depository accounts are unavailable. USER\_FRAUD\_ALERT: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, USER\_FRAUD\_ALERT

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

```json
{
  "request_id": "LhQf0THi8SH1yJm",
  "report": {
    "report_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "client_report_id": "client_report_id_1221",
    "generated_time": "2022-01-31T22:47:53Z",
    "items": [
      {
        "institution_id": "ins_109508",
        "institution_name": "Plaid Bank",
        "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
        "accounts": [
          {
            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
            "mask": "8888",
            "metadata": {
              "start_date": "2022-01-01",
              "end_date": "2022-01-31"
            },
            "name": "Plaid Checking Account",
            "official_name": "Plaid Checking Account",
            "type": "depository",
            "subtype": "checking",
            "owners": []
          }
        ]
      }
    ],
    "prism": {
      "insights": {
        "version": 3,
        "result": {
          "l6m_cumbal_acc": 1
        }
      },
      "cash_score": {
        "version": 3,
        "model_version": "3",
        "score": 900,
        "reason_codes": [
          "CS03038"
        ],
        "metadata": {
          "max_age": 20,
          "min_age": 1,
          "min_age_credit": 0,
          "min_age_debit": 1,
          "max_age_debit": 20,
          "max_age_credit": 0,
          "num_trxn_credit": 0,
          "num_trxn_debit": 40,
          "l1m_credit_value_cnt": 0,
          "l1m_debit_value_cnt": 40
        }
      },
      "first_detect": {
        "version": 3,
        "model_version": "3",
        "score": 900,
        "reason_codes": [
          "CS03038"
        ],
        "metadata": {
          "max_age": 20,
          "min_age": 1,
          "min_age_credit": 0,
          "min_age_debit": 1,
          "max_age_debit": 20,
          "max_age_credit": 0,
          "num_trxn_credit": 0,
          "num_trxn_debit": 40,
          "l1m_credit_value_cnt": 0,
          "l1m_debit_value_cnt": 40
        }
      },
      "status": "SUCCESS"
    }
  }
}
```

\=\*=\*=\*=

#### /cra/check\_report/pdf/get 

#### Retrieve Consumer Reports as a PDF 

[/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) retrieves the most recent Consumer Report in PDF format. By default, the most recent Base Report (if it exists) for the user will be returned. To request that the most recent Income Insights report be included in the PDF as well, use the `add-ons` field.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

**add\_ons** (\[string\])  
Use this field to include other reports in the PDF. Possible values: cra\_income\_insights

```javascript
try {
  const response = await client.craCheckReportPDFGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  });
  const pdf = response.buffer.toString('base64');
} catch (error) {
  // handle error
}
```

##### Response 

This endpoint returns binary PDF data. [View a sample Check Report PDF.](https://plaid.com/documents/sample-check-report.pdf) [View a sample Check Report PDF containing Income Insights.](https://plaid.com/documents/sample-check-report-with-income.pdf)

\=\*=\*=\*=

#### /cra/check\_report/verification/get 

#### Retrieve various verification reports for a user. 

This endpoint allows you to retrieve verification reports for a user. To obtain a VoA or Employment Refresh report, you need to make sure that `cra_base_report` is included in the `products` parameter when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .  
You should call this endpoint after you've received a `CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .  
If the most recent consumer report for the user doesn’t have sufficient data to generate the report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) ."

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

**reports\_requested** (required, \[string\])  
Specifies which types of verification reports are expected in the response Possible values: VOA, EMPLOYMENT\_REFRESH

**employment\_refresh\_options** (object)  
Defines configuration options for the Employment Refresh Report.

**employment\_refresh\_options->days\_requested** (required, integer)  
The number of days of data to request for the report. This field is required if an Employment Refresh Report is requested. Maximum is 731. Maximum: 731

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
try {
  const response = await client.craCheckReportVerificationGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
    reports_requested: ['VOA', 'EMPLOYMENT_REFRESH'],
    employment_refresh_options: {
      days_requested: 60,
    },
  });
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**report** (object)  
Contains data for the CRA Verification Report.

**report->report\_id** (string)  
The unique identifier associated with the Verification Report object. This ID will be the same as the Base Report ID.

**report->client\_report\_id** (nullable, string)  
Client-generated identifier, which can be used by lenders to track loan applications.

**report->voa** (nullable, object)  
An object representing a VOA report.

**report->voa->generated\_time** (string)  
The date and time when the VOA Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time

**report->voa->days\_requested** (number)  
The number of days of transaction history that the VOA report covers.

**report->voa->items** (\[object\])  
Data returned by Plaid about each of the Items included in the Base Report.

**report->voa->items->accounts** (\[object\])  
Data about each of the accounts open on the Item.

**report->voa->items->accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->voa->items->accounts->balances** (object)  
VOA Report information about an account's balances.

**report->voa->items->accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**report->voa->items->accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**report->voa->items->accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->voa->items->accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->voa->items->accounts->balances->historical\_balances** (\[object\])  
Calculated data about the historical balances on the account.

**report->voa->items->accounts->balances->historical\_balances->current** (number)  
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction. Format: double

**report->voa->items->accounts->balances->historical\_balances->date** (string)  
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->voa->items->accounts->balances->historical\_balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**report->voa->items->accounts->balances->historical\_balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->voa->items->accounts->balances->average\_balance\_30\_days** (nullable, number)  
The average balance in the account over the last 30 days. Calculated using the derived historical balances. Format: double

**report->voa->items->accounts->balances->average\_balance\_60\_days** (nullable, number)  
The average balance in the account over the last 60 days. Calculated using the derived historical balances. Format: double

**report->voa->items->accounts->balances->nsf\_overdraft\_transactions\_count** (number)  
The number of NSF and overdraft fee transactions in the time range for the report in the given account.

**report->voa->items->accounts->consumer\_disputes** (\[object\])  
The information about previously submitted valid dispute statements by the consumer

**report->voa->items->accounts->consumer\_disputes->consumer\_dispute\_id** (deprecated, string)  
(Deprecated) A unique identifier (UUID) of the consumer dispute that can be used for troubleshooting

**report->voa->items->accounts->consumer\_disputes->dispute\_field\_create\_date** (string)  
Date of the disputed field (e.g. transaction date), in an ISO 8601 format (YYYY-MM-DD) Format: date

**report->voa->items->accounts->consumer\_disputes->category** (string)  
Type of data being disputed by the consumer Possible values: TRANSACTION, BALANCE, IDENTITY, OTHER

**report->voa->items->accounts->consumer\_disputes->statement** (string)  
Text content of dispute

**report->voa->items->accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**report->voa->items->accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself.

**report->voa->items->accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution.

**report->voa->items->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**report->voa->items->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**report->voa->items->accounts->days\_available** (number)  
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.

**report->voa->items->accounts->transactions\_insights** (object)  
Transaction data associated with the account.

**report->voa->items->accounts->transactions\_insights->all\_transactions** (\[object\])  
Transaction history associated with the account.

**report->voa->items->accounts->transactions\_insights->all\_transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**report->voa->items->accounts->transactions\_insights->all\_transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: double

**report->voa->items->accounts->transactions\_insights->all\_transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**report->voa->items->accounts->transactions\_insights->all\_transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**report->voa->items->accounts->transactions\_insights->all\_transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**report->voa->items->accounts->transactions\_insights->all\_transactions->credit\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the taxonomy csv file for a full list of credit categories.

**report->voa->items->accounts->transactions\_insights->all\_transactions->credit\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**report->voa->items->accounts->transactions\_insights->all\_transactions->credit\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**report->voa->items->accounts->transactions\_insights->all\_transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**report->voa->items->accounts->transactions\_insights->all\_transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**report->voa->items->accounts->transactions\_insights->all\_transactions->date\_transacted** (nullable, string)  
The date on which the transaction took place, in IS0 8601 format.

**report->voa->items->accounts->transactions\_insights->all\_transactions->location** (object)  
A representation of where a transaction took place

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**report->voa->items->accounts->transactions\_insights->all\_transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**report->voa->items->accounts->transactions\_insights->all\_transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**report->voa->items->accounts->transactions\_insights->all\_transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->voa->items->accounts->transactions\_insights->all\_transactions->account\_owner** (nullable, string)  
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.

**report->voa->items->accounts->transactions\_insights->all\_transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->voa->items->accounts->transactions\_insights->end\_date** (nullable, string)  
The latest timeframe provided by the FI, in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->voa->items->accounts->transactions\_insights->start\_date** (nullable, string)  
The earliest timeframe provided by the FI, in an ISO 8601 format (YYYY-MM-DD). Format: date

**report->voa->items->accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners.

**report->voa->items->accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**report->voa->items->accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->voa->items->accounts->owners->phone\_numbers->data** (string)  
The phone number.

**report->voa->items->accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**report->voa->items->accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**report->voa->items->accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->voa->items->accounts->owners->emails->data** (string)  
The email address.

**report->voa->items->accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**report->voa->items->accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**report->voa->items->accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**report->voa->items->accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**report->voa->items->accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**report->voa->items->accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**report->voa->items->accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**report->voa->items->accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**report->voa->items->accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**report->voa->items->accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**report->voa->items->accounts->ownership\_type** (nullable, string)  
How an asset is owned. association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust. Possible values: null, individual, joint, association, trust

**report->voa->items->institution\_name** (string)  
The full financial institution name associated with the Item.

**report->voa->items->institution\_id** (string)  
The id of the financial institution associated with the Item.

**report->voa->items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**report->voa->items->last\_update\_time** (string)  
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format. Format: date-time

**report->voa->attributes** (object)  
Attributes for the VOA report.

**report->voa->attributes->total\_inflow\_amount** (nullable, object)  
Total amount of debit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts.

**report->voa->attributes->total\_inflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->voa->attributes->total\_inflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->voa->attributes->total\_inflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->voa->attributes->total\_outflow\_amount** (nullable, object)  
Total amount of credit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts.

**report->voa->attributes->total\_outflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**report->voa->attributes->total\_outflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**report->voa->attributes->total\_outflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**report->employment\_refresh** (nullable, object)  
An object representing an Employment Refresh Report.

**report->employment\_refresh->generated\_time** (string)  
The date and time when the Employment Refresh Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time

**report->employment\_refresh->days\_requested** (number)  
The number of days of transaction history that the Employment Refresh Report covers.

**report->employment\_refresh->items** (\[object\])  
Data returned by Plaid about each of the Items included in the Employment Refresh Report.

**report->employment\_refresh->items->accounts** (\[object\])  
Data about each of the accounts open on the Item.

**report->employment\_refresh->items->accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**report->employment\_refresh->items->accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself.

**report->employment\_refresh->items->accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution.

**report->employment\_refresh->items->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**report->employment\_refresh->items->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**report->employment\_refresh->items->accounts->transactions** (\[object\])  
Transaction history associated with the account for the Employment Refresh Report. Note that this transaction differs from a Base Report transaction in that it will only be deposits, and the amounts will be omitted.

**report->employment\_refresh->items->accounts->transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**report->employment\_refresh->items->accounts->transactions->original\_description** (string)  
The string returned by the financial institution to describe the transaction.

**report->employment\_refresh->items->accounts->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**report->employment\_refresh->items->accounts->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**report->employment\_refresh->items->accounts->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**report->employment\_refresh->items->institution\_name** (string)  
The full financial institution name associated with the Item.

**report->employment\_refresh->items->institution\_id** (string)  
The id of the financial institution associated with the Item.

**report->employment\_refresh->items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**report->employment\_refresh->items->last\_update\_time** (string)  
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**warnings** (\[object\])  
If the verification report generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing.

**warnings->warning\_type** (string)  
The warning type, which will always be CHECK\_REPORT\_WARNING

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Account-owner information is not available. TRANSACTIONS\_UNAVAILABLE: Transactions information associated with Credit and Depository accounts are unavailable. USER\_FRAUD\_ALERT: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, USER\_FRAUD\_ALERT

**warnings->cause** (nullable, object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**warnings->cause->error\_code** (string)  
The particular error code. Safe for programmatic use.

**warnings->cause->error\_code\_reason** (nullable, 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.

**warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**warnings->cause->display\_message** (nullable, 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.

**warnings->cause->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.

**warnings->cause->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.

**warnings->cause->status** (nullable, 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.

**warnings->cause->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**warnings->cause->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

```json
{
  "request_id": "LhQf0THi8SH1yJm",
  "report": {
    "report_id": "028e8404-a013-4a45-ac9e-002482f9cafc",
    "client_report_id": "client_report_id_1221",
    "voa": {
      "generated_time": "2023-03-30T18:27:37Z",
      "days_requested": 90,
      "attributes": {
        "total_inflow_amount": {
          "amount": 345.12,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        },
        "total_outflow_amount": {
          "amount": 235.12,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      },
      "items": [
        {
          "accounts": [
            {
              "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
              "balances": {
                "available": 100,
                "current": 110,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "historical_balances": [
                  {
                    "current": 110,
                    "date": "2023-03-29",
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  },
                  {
                    "current": 125.55,
                    "date": "2023-03-28",
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  },
                  {
                    "current": 80.13,
                    "date": "2023-03-27",
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  },
                  {
                    "current": 246.11,
                    "date": "2023-03-26",
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  },
                  {
                    "current": 182.71,
                    "date": "2023-03-25",
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "average_balance_30_days": 200,
                "average_balance_60_days": 150,
                "average_balance_90_days": 125,
                "nsf_overdraft_transactions_count": 0
              },
              "consumer_disputes": [],
              "mask": "0000",
              "name": "Plaid Checking",
              "official_name": "Plaid Gold Standard 0% Interest Checking",
              "type": "depository",
              "subtype": "checking",
              "days_available": 90,
              "transactions_insights": {
                "all_transactions": [
                  {
                    "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                    "amount": 89.4,
                    "date": "2023-03-27",
                    "iso_currency_code": "USD",
                    "original_description": "SparkFun",
                    "pending": false,
                    "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD",
                    "unofficial_currency_code": null
                  },
                  {
                    "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                    "amount": 12,
                    "date": "2023-03-28",
                    "iso_currency_code": "USD",
                    "original_description": "McDonalds #3322",
                    "pending": false,
                    "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL",
                    "unofficial_currency_code": null
                  },
                  {
                    "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                    "amount": 4.33,
                    "date": "2023-03-28",
                    "iso_currency_code": "USD",
                    "original_description": "Starbucks",
                    "pending": false,
                    "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy",
                    "unofficial_currency_code": null
                  },
                  {
                    "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                    "amount": -500,
                    "date": "2023-03-29",
                    "iso_currency_code": "USD",
                    "original_description": "United Airlines **** REFUND ****",
                    "pending": false,
                    "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5",
                    "unofficial_currency_code": null
                  }
                ],
                "end_date": "2024-07-31",
                "start_date": "2024-07-01"
              },
              "owners": [
                {
                  "addresses": [
                    {
                      "data": {
                        "city": "Malakoff",
                        "country": "US",
                        "region": "NY",
                        "street": "2992 Cameron Road",
                        "postal_code": "14236"
                      },
                      "primary": true
                    },
                    {
                      "data": {
                        "city": "San Matias",
                        "country": "US",
                        "region": "CA",
                        "street": "2493 Leisure Lane",
                        "postal_code": "93405-2255"
                      },
                      "primary": false
                    }
                  ],
                  "emails": [
                    {
                      "data": "accountholder0@example.com",
                      "primary": true,
                      "type": "primary"
                    },
                    {
                      "data": "accountholder1@example.com",
                      "primary": false,
                      "type": "secondary"
                    },
                    {
                      "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                      "primary": false,
                      "type": "other"
                    }
                  ],
                  "names": [
                    "Alberta Bobbeth Charleson"
                  ],
                  "phone_numbers": [
                    {
                      "data": "+1 111-555-3333",
                      "primary": false,
                      "type": "home"
                    },
                    {
                      "data": "+1 111-555-4444",
                      "primary": false,
                      "type": "work"
                    },
                    {
                      "data": "+1 111-555-5555",
                      "primary": false,
                      "type": "mobile"
                    }
                  ]
                }
              ],
              "ownership_type": null
            }
          ],
          "institution_name": "First Platypus Bank",
          "institution_id": "ins_109508",
          "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7",
          "last_update_time": "2023-03-30T18:25:26Z"
        }
      ]
    },
    "employment_refresh": {
      "generated_time": "2023-03-30T18:27:37Z",
      "days_requested": 60,
      "items": [
        {
          "accounts": [
            {
              "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
              "name": "Plaid Money Market",
              "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
              "type": "depository",
              "subtype": "money market",
              "transactions": [
                {
                  "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
                  "original_description": "ACH Electronic CreditGUSTO PAY 123456",
                  "date": "2023-03-30",
                  "pending": false,
                  "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78"
                }
              ]
            },
            {
              "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
              "name": "Plaid Checking",
              "official_name": "Plaid Gold Standard 0% Interest Checking",
              "type": "depository",
              "subtype": "checking",
              "transactions": [
                {
                  "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
                  "original_description": "United Airlines **** REFUND ****",
                  "date": "2023-03-29",
                  "pending": false,
                  "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5"
                }
              ]
            }
          ],
          "institution_name": "First Platypus Bank",
          "institution_id": "ins_109508",
          "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7",
          "last_update_time": "2023-03-30T18:25:26Z"
        }
      ]
    }
  },
  "warnings": []
}
```

\=\*=\*=\*=

#### /cra/monitoring\_insights/get 

#### Retrieve a Monitoring Insights Report 

This endpoint allows you to retrieve a Monitoring Insights report by passing in the `user_token` referred to in the webhook you received.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**consumer\_report\_permissible\_purpose** (required, string)  
Describes the reason you are generating a Consumer Report for this user. 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). 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. Possible values: ACCOUNT\_REVIEW\_CREDIT, WRITTEN\_INSTRUCTION\_OTHER

```javascript
try {
  const response = await client.craMonitoringInsightsGet({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
    consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT',
  });
} catch (error) {
  // handle error
}
```

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

**user\_insights\_id** (string)  
A unique ID identifying a User Monitoring Insights Report. Like all Plaid identifiers, this ID is case sensitive.

**items** (\[object\])  
An array of Monitoring Insights Items associated with the user.

**items->date\_generated** (string)  
The date and time when the specific insights were generated (per-item), in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time

**items->item\_id** (string)  
The item\_id of the Item associated with the insights

**items->institution\_id** (string)  
The id of the financial institution associated with the Item.

**items->institution\_name** (string)  
The full financial institution name associated with the Item.

**items->status** (object)  
An object with details of the Monitoring Insights Item's status.

**items->status->status\_code** (string)  
Enum for the status of the Item's insights Possible values: AVAILABLE, FAILED, PENDING

**items->status->reason** (nullable, string)  
A reason for why a Monitoring Insights Report is not available. This field will only be populated when the status\_code is not AVAILABLE

**items->insights** (nullable, object)  
An object representing the Monitoring Insights for the given Item

**items->insights->income** (object)  
An object representing the income subcategory of the report

**items->insights->income->total\_monthly\_income** (object)  
Details about about the total monthly income

**items->insights->income->total\_monthly\_income->baseline\_amount** (number)  
The aggregated income for the 30 days prior to subscription date

**items->insights->income->total\_monthly\_income->current\_amount** (number)  
The aggregated income of the last 30 days

**items->insights->income->income\_sources\_counts** (object)  
Details about the number of income sources

**items->insights->income->income\_sources\_counts->baseline\_count** (number)  
The number of income sources detected at the subscription date

**items->insights->income->income\_sources\_counts->current\_count** (number)  
The number of income sources currently detected

**items->insights->income->forecasted\_monthly\_income** (object)  
An object representing the predicted average monthly net income amount. This amount reflects the funds deposited into the account and may not include any withheld income such as taxes or other payroll deductions

**items->insights->income->forecasted\_monthly\_income->baseline\_amount** (number)  
The forecasted monthly income at the time of subscription

**items->insights->income->forecasted\_monthly\_income->current\_amount** (number)  
The current forecasted monthly income

**items->insights->income->historical\_annual\_income** (object)  
An object representing the historical annual income amount.

**items->insights->income->historical\_annual\_income->baseline\_amount** (number)  
The historical annual income at the time of subscription

**items->insights->income->historical\_annual\_income->current\_amount** (number)  
The current historical annual income

**items->insights->income->income\_sources** (\[object\])  
The income sources for this Item. Each entry in the array is a single income source

**items->insights->income->income\_sources->income\_source\_id** (string)  
A unique identifier for an income source

**items->insights->income->income\_sources->income\_description** (string)  
The most common name or original description for the underlying income transactions

**items->insights->income->income\_sources->income\_category** (string)  
The income category. BANK\_INTEREST: Interest earned from a bank account. BENEFIT\_OTHER: Government benefits other than retirement, unemployment, child support, or disability. Currently used only in the UK, to represent benefits such as Cost of Living Payments. CASH: Deprecated and used only for existing legacy implementations. Has been replaced by CASH\_DEPOSIT and TRANSFER\_FROM\_APPLICATION. CASH\_DEPOSIT: A cash or check deposit. CHILD\_SUPPORT: Child support payments received. GIG\_ECONOMY: Income earned as a gig economy worker, e.g. driving for Uber, Lyft, Postmates, DoorDash, etc. LONG\_TERM\_DISABILITY: Disability payments, including Social Security disability benefits. OTHER: Income that could not be categorized as any other income category. MILITARY: Veterans benefits. Income earned as salary for serving in the military (e.g. through DFAS) will be classified as SALARY rather than MILITARY. RENTAL: Income earned from a rental property. Income may be identified as rental when the payment is received through a rental platform, e.g. Airbnb; rent paid directly by the tenant to the property owner (e.g. via cash, check, or ACH) will typically not be classified as rental income. RETIREMENT: Payments from private retirement systems, pensions, and government retirement programs, including Social Security retirement benefits. SALARY: Payment from an employer to an earner or other form of permanent employment. TAX\_REFUND: A tax refund. TRANSFER\_FROM\_APPLICATION: Deposits from a money transfer app, such as Venmo, Cash App, or Zelle. UNEMPLOYMENT: Unemployment benefits. In the UK, includes certain low-income benefits such as the Universal Credit. Possible values: SALARY, UNEMPLOYMENT, CASH, GIG\_ECONOMY, RENTAL, CHILD\_SUPPORT, MILITARY, RETIREMENT, LONG\_TERM\_DISABILITY, BANK\_INTEREST, CASH\_DEPOSIT, TRANSFER\_FROM\_APPLICATION, TAX\_REFUND, BENEFIT\_OTHER, OTHER

**items->insights->income->income\_sources->last\_transaction\_date** (string)  
The last detected transaction date for this income source Format: date

**items->insights->loans** (object)  
An object representing the loan exposure subcategory of the report

**items->insights->loans->loan\_payments\_counts** (object)  
Details regarding the number of loan payments

**items->insights->loans->loan\_payments\_counts->baseline\_count** (number)  
The number of loan payments made in the 30 days before the subscription date

**items->insights->loans->loan\_payments\_counts->current\_count** (number)  
The current number of loan payments made in the last 30 days

**items->insights->loans->loan\_disbursements\_count** (number)  
The number of loan disbursements detected in the last 30 days

**items->insights->loans->loan\_payment\_merchants\_counts** (object)  
Details regarding the number of unique loan payment merchants

**items->insights->loans->loan\_payment\_merchants\_counts->baseline\_count** (number)  
The number of unique loan payment merchants detected in the 30 days before the subscription date

**items->insights->loans->loan\_payment\_merchants\_counts->current\_count** (number)  
The current number of unique loan payment merchants detected in the last 30 days

**items->accounts** (\[object\])  
Data about each of the accounts open on the Item.

**items->accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account\_id is case sensitive.

**items->accounts->balances** (object)  
Information about an account's balances.

**items->accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**items->accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**items->accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**items->accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**items->accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**items->accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get. This field is only used and expected when the institution is ins\_128026 (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID\_REQUEST error with the code of INVALID\_FIELD will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an INVALID\_REQUEST error with the code of LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE will be returned with the most recent timestamp for the requested account contained in the response. Format: date-time

**items->accounts->balances->average\_balance** (nullable, number)  
The average historical balance for the entire report Format: double

**items->accounts->balances->average\_monthly\_balances** (\[object\])  
The average historical balance of each calendar month

**items->accounts->balances->average\_monthly\_balances->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

**items->accounts->balances->average\_monthly\_balances->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

**items->accounts->balances->average\_monthly\_balances->average\_balance** (object)  
This contains an amount, denominated in the currency specified by either iso\_currency\_code or unofficial\_currency\_code

**items->accounts->balances->average\_monthly\_balances->average\_balance->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->balances->average\_monthly\_balances->average\_balance->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->balances->average\_monthly\_balances->average\_balance->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->balances->most\_recent\_thirty\_day\_average\_balance** (nullable, number)  
The average historical balance from the most recent 30 days Format: double

**items->accounts->consumer\_disputes** (\[object\])  
The information about previously submitted valid dispute statements by the consumer

**items->accounts->consumer\_disputes->consumer\_dispute\_id** (deprecated, string)  
(Deprecated) A unique identifier (UUID) of the consumer dispute that can be used for troubleshooting

**items->accounts->consumer\_disputes->dispute\_field\_create\_date** (string)  
Date of the disputed field (e.g. transaction date), in an ISO 8601 format (YYYY-MM-DD) Format: date

**items->accounts->consumer\_disputes->category** (string)  
Type of data being disputed by the consumer Possible values: TRANSACTION, BALANCE, IDENTITY, OTHER

**items->accounts->consumer\_disputes->statement** (string)  
Text content of dispute

**items->accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**items->accounts->metadata** (object)  
Metadata about the extracted account.

**items->accounts->metadata->start\_date** (nullable, string)  
The beginning of the range of the financial institution provided data for the account, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**items->accounts->metadata->end\_date** (nullable, string)  
The end of the range of the financial institution provided data for the account, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**items->accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**items->accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**items->accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**items->accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**items->accounts->days\_available** (number)  
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.

**items->accounts->transactions** (\[object\])  
Transaction history associated with the account. Transaction history returned by endpoints such as /transactions/get or /investments/transactions/get will be returned in the top-level transactions field instead.

**items->accounts->transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**items->accounts->transactions->amount** (number)  
The settled value of the transaction, denominated in the transaction's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: double

**items->accounts->transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**items->accounts->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**items->accounts->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**items->accounts->transactions->credit\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the taxonomy csv file for a full list of credit categories.

**items->accounts->transactions->credit\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**items->accounts->transactions->credit\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**items->accounts->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**items->accounts->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**items->accounts->transactions->date\_transacted** (nullable, string)  
The date on which the transaction took place, in IS0 8601 format.

**items->accounts->transactions->location** (object)  
A representation of where a transaction took place

**items->accounts->transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**items->accounts->transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**items->accounts->transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**items->accounts->transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**items->accounts->transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**items->accounts->transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**items->accounts->transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**items->accounts->transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**items->accounts->transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**items->accounts->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**items->accounts->transactions->account\_owner** (nullable, string)  
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.

**items->accounts->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**items->accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. This array can also be empty if no owners are found.

**items->accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**items->accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**items->accounts->owners->phone\_numbers->data** (string)  
The phone number.

**items->accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**items->accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**items->accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**items->accounts->owners->emails->data** (string)  
The email address.

**items->accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**items->accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**items->accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**items->accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**items->accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**items->accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**items->accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**items->accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**items->accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**items->accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**items->accounts->ownership\_type** (nullable, string)  
How an asset is owned. association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust. Possible values: null, individual, joint, association, trust

**items->accounts->account\_insights** (deprecated, object)  
Calculated insights derived from transaction-level data. This field has been deprecated in favor of Base Report attributes aggregated across accounts and will be removed in a future release.

**items->accounts->account\_insights->oldest\_transaction\_date** (nullable, string)  
Date of the earliest transaction for the account. Format: date

**items->accounts->account\_insights->most\_recent\_transaction\_date** (nullable, string)  
Date of the most recent transaction for the account. Format: date

**items->accounts->account\_insights->days\_available** (integer)  
Number of days days available for the account.

**items->accounts->account\_insights->average\_days\_between\_transactions** (number)  
Average number of days between sequential transactions

**items->accounts->account\_insights->longest\_gaps\_between\_transactions** (\[object\])  
Longest gap between sequential transactions in a time period. This array can include multiple time periods.

**items->accounts->account\_insights->longest\_gaps\_between\_transactions->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->longest\_gaps\_between\_transactions->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->longest\_gaps\_between\_transactions->days** (nullable, integer)  
Largest number of days between sequential transactions for this time period.

**items->accounts->account\_insights->number\_of\_inflows** (\[object\])  
The number of debits into the account. This array will be empty for non-depository accounts.

**items->accounts->account\_insights->number\_of\_inflows->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->number\_of\_inflows->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->number\_of\_inflows->count** (integer)  
The number of credits or debits out of the account for this time period.

**items->accounts->account\_insights->average\_inflow\_amounts** (\[object\])  
Average amount of debit transactions into the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->account\_insights->average\_inflow\_amounts->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->average\_inflow\_amounts->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->average\_inflow\_amounts->total\_amount** (object)  
This contains an amount, denominated in the currency specified by either iso\_currency\_code or unofficial\_currency\_code

**items->accounts->account\_insights->average\_inflow\_amounts->total\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->account\_insights->average\_inflow\_amounts->total\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->account\_insights->average\_inflow\_amounts->total\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->account\_insights->number\_of\_outflows** (\[object\])  
The number of outflows from the account. This array will be empty for non-depository accounts.

**items->accounts->account\_insights->number\_of\_outflows->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->number\_of\_outflows->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->number\_of\_outflows->count** (integer)  
The number of credits or debits out of the account for this time period.

**items->accounts->account\_insights->average\_outflow\_amounts** (\[object\])  
Average amount of transactions out of the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->account\_insights->average\_outflow\_amounts->start\_date** (string)  
The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->average\_outflow\_amounts->end\_date** (string)  
The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**items->accounts->account\_insights->average\_outflow\_amounts->total\_amount** (object)  
This contains an amount, denominated in the currency specified by either iso\_currency\_code or unofficial\_currency\_code

**items->accounts->account\_insights->average\_outflow\_amounts->total\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->account\_insights->average\_outflow\_amounts->total\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->account\_insights->average\_outflow\_amounts->total\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->account\_insights->number\_of\_days\_no\_transactions** (integer)  
Number of days with no transactions

**items->accounts->attributes** (object)  
Calculated attributes derived from transaction-level data.

**items->accounts->attributes->is\_primary\_account** (nullable, boolean)  
Prediction indicator of whether the account is a primary account. Only one account per account type across the items connected will have a value of true.

**items->accounts->attributes->primary\_account\_score** (nullable, number)  
Value ranging from 0-1. The higher the score, the more confident we are of the account being the primary account.

**items->accounts->attributes->nsf\_overdraft\_transactions\_count** (integer)  
The number of NSF and overdraft fee transactions in the time range for the report in the given account.

**items->accounts->attributes->nsf\_overdraft\_transactions\_count\_30d** (integer)  
The number of NSF and overdraft fee transactions in the last 30 days for a given account.

**items->accounts->attributes->nsf\_overdraft\_transactions\_count\_60d** (integer)  
The number of NSF and overdraft fee transactions in the last 60 days for a given account.

**items->accounts->attributes->nsf\_overdraft\_transactions\_count\_90d** (integer)  
The number of NSF and overdraft fee transactions in the last 90 days for a given account.

**items->accounts->attributes->total\_inflow\_amount** (nullable, object)  
Total amount of debit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_inflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_inflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_inflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_inflow\_amount\_30d** (nullable, object)  
Total amount of debit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_inflow\_amount\_30d->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_inflow\_amount\_30d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_inflow\_amount\_30d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_inflow\_amount\_60d** (nullable, object)  
Total amount of debit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_inflow\_amount\_60d->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_inflow\_amount\_60d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_inflow\_amount\_60d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_inflow\_amount\_90d** (nullable, object)  
Total amount of debit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_inflow\_amount\_90d->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_inflow\_amount\_90d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_inflow\_amount\_90d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_outflow\_amount** (nullable, object)  
Total amount of credit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_outflow\_amount->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_outflow\_amount->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_outflow\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_outflow\_amount\_30d** (nullable, object)  
Total amount of credit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_outflow\_amount\_30d->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_outflow\_amount\_30d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_outflow\_amount\_30d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_outflow\_amount\_60d** (nullable, object)  
Total amount of credit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_outflow\_amount\_60d->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_outflow\_amount\_60d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_outflow\_amount\_60d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**items->accounts->attributes->total\_outflow\_amount\_90d** (nullable, object)  
Total amount of credit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account.

**items->accounts->attributes->total\_outflow\_amount\_90d->amount** (number)  
Value of amount with up to 2 decimal places.

**items->accounts->attributes->total\_outflow\_amount\_90d->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**items->accounts->attributes->total\_outflow\_amount\_90d->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

```json
{
  "user_insights_id": "028e8404-a013-4a45-ac9e-002482f9cafc",
  "items": [
    {
      "date_generated": "2023-03-30T18:27:37Z",
      "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7",
      "institution_id": "ins_0",
      "institution_name": "Plaid Bank",
      "status": {
        "status_code": "AVAILABLE"
      },
      "insights": {
        "income": {
          "income_sources": [
            {
              "income_source_id": "f17efbdd-caab-4278-8ece-963511cd3d51",
              "income_description": "“PLAID_INC_DIRECT_DEP_PPD”",
              "income_category": "SALARY",
              "last_transaction_date": "2023-03-30"
            }
          ],
          "forecasted_monthly_income": {
            "baseline_amount": 10000,
            "current_amount": 12000
          },
          "total_monthly_income": {
            "baseline_amount": 10770.93,
            "current_amount": 20000.31
          },
          "historical_annual_income": {
            "baseline_amount": 120000,
            "current_amount": 144000
          },
          "income_sources_counts": {
            "baseline_count": 1,
            "current_count": 1
          }
        },
        "loans": {
          "loan_payments_counts": {
            "baseline_count": 1,
            "current_count": 1
          },
          "loan_payment_merchants_counts": {
            "baseline_count": 1,
            "current_count": 1
          },
          "loan_disbursements_count": 1
        }
      }
    }
  ],
  "request_id": "m8MDnv9okwxFNBV"
}
```

\=\*=\*=\*=

#### /cra/monitoring\_insights/subscribe 

#### Subscribe to Monitoring Insights 

This endpoint allows you to subscribe to insights for a user's linked CRA items, which are updated between one and four times per day (best-effort).

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**webhook** (required, string)  
URL to which Plaid will send Monitoring Insights webhooks, for example when the requested Monitoring Insights is ready.

**income\_categories** (\[string\])  
Income categories to include in Cash Flow Updates. If empty or null, this field will default to including all possible categories. Possible values: SALARY, UNEMPLOYMENT, CASH, GIG\_ECONOMY, RENTAL, CHILD\_SUPPORT, MILITARY, RETIREMENT, LONG\_TERM\_DISABILITY, BANK\_INTEREST, CASH\_DEPOSIT, TRANSFER\_FROM\_APPLICATION, TAX\_REFUND, BENEFIT\_OTHER, OTHER

```javascript
try {
  const response = await client.craMonitoringInsightsSubscribe({
    user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
    webhook: 'https://example.com/webhook',
    income_categories: [CreditBankIncomeCategory.Salary],
  });
} catch (error) {
  // handle error
}
```

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

**subscription\_id** (string)  
A unique identifier for the subscription.

```json
{
  "subscription_id": "f17efbdd-caab-4278-8ece-963511cd3d51",
  "request_id": "GVzMdiDd8DDAQK4"
}
```

\=\*=\*=\*=

#### /cra/monitoring\_insights/unsubscribe 

#### Unsubscribe from Monitoring Insights 

This endpoint allows you to unsubscribe from previously subscribed Monitoring Insights.

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

**subscription\_id** (required, string)  
A unique identifier for the subscription.

```javascript
try {
  const response = await client.craMonitoringInsightsUnsubscribe({
    subscription_id: '"f17efbdd-caab-4278-8ece-963511cd3d51"',
  });
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "GVzMdiDd8DDAQK4"
}
```

### Webhooks 

When you create a new report, either by creating a Link token with a Plaid Check product, or by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , Plaid Check will start generating a report for you. When the report has been created (or the report creation fails), Plaid Check will let you know by sending you either a `CHECK_REPORT: CHECK_REPORT_READY` or `CHECK_REPORT: CHECK_REPORT_FAILED` webhook.

\=\*=\*=\*=

#### CHECK\_REPORT\_READY 

Fired when the Check Report are ready to be retrieved. Once this webhook has fired, the report will be available to retrieve for 24 hours.

#### Properties 

**webhook\_type** (string)  
CHECK\_REPORT

**webhook\_code** (string)  
CHECK\_REPORT\_READY

**user\_id** (string)  
The user\_id corresponding to the user the webhook has fired for.

**successful\_products** (\[string\])  
Specifies a list of products that have successfully been generated for the report. Possible values: cra\_base\_report, cra\_income\_insights, cra\_cashflow\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_monitoring

**failed\_products** (\[string\])  
Specifies a list of products that have failed to generate for the report. Additional detail on what caused the failure can be found by calling the product /get endpoint. Possible values: cra\_base\_report, cra\_income\_insights, cra\_cashflow\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_monitoring

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CHECK_REPORT",
  "webhook_code": "CHECK_REPORT_READY",
  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "successful_products": [
    "cra_base_report"
  ],
  "environment": "production"
}
```

\=\*=\*=\*=

#### CHECK\_REPORT\_FAILED 

Fired when a Check Report has failed to generate

#### Properties 

**webhook\_type** (string)  
CHECK\_REPORT

**webhook\_code** (string)  
CHECK\_REPORT\_FAILED

**user\_id** (string)  
The user\_id corresponding to the user the webhook has fired for.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CHECK_REPORT",
  "webhook_code": "CHECK_REPORT_FAILED",
  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "environment": "production"
}
```

### Cash flow updates webhooks 

These webhooks are specific to the Cash Flow Updates (beta) product.

\=\*=\*=\*=

#### INSIGHTS\_UPDATED 

For each user's item enabled for Cash Flow Updates, this webhook will fire between one and four times a day with information on the status of the update. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights.

#### Properties 

**webhook\_type** (string)  
CASH\_FLOW\_UPDATES

**webhook\_code** (string)  
INSIGHTS\_UPDATED

**status** (string)  
Enum for the status of the insights Possible values: AVAILABLE, FAILED

**user\_id** (string)  
The user\_id that the report is associated with

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CASH_FLOW_UPDATES",
  "webhook_code": "INSIGHTS_UPDATED",
  "status": "AVAILABLE",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "environment": "production"
}
```

\=\*=\*=\*=

#### LARGE\_DEPOSIT\_DETECTED 

For each user's item enabled for Cash Flow Updates, this webhook will fire when an update detects a deposit over $5,000. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights.

#### Properties 

**webhook\_type** (string)  
CASH\_FLOW\_UPDATES

**webhook\_code** (string)  
LARGE\_DEPOSIT\_DETECTED

**status** (string)  
Enum for the status of the insights Possible values: AVAILABLE, FAILED

**user\_id** (string)  
The user\_id that the report is associated with

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CASH_FLOW_UPDATES",
  "webhook_code": "LARGE_DEPOSIT_DETECTED",
  "status": "AVAILABLE",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "environment": "production"
}
```

\=\*=\*=\*=

#### LOW\_BALANCE\_DETECTED 

For each user's item enabled for Cash Flow Updates, this webhook will fire when an update detects a balance below $100. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights.

#### Properties 

**webhook\_type** (string)  
CASH\_FLOW\_UPDATES

**webhook\_code** (string)  
LOW\_BALANCE\_DETECTED

**status** (string)  
Enum for the status of the insights Possible values: AVAILABLE, FAILED

**user\_id** (string)  
The user\_id that the report is associated with

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CASH_FLOW_UPDATES",
  "webhook_code": "LOW_BALANCE_DETECTED",
  "status": "AVAILABLE",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "environment": "production"
}
```

\=\*=\*=\*=

#### NEW\_LOAN\_PAYMENT\_DETECTED 

For each user's item enabled for Cash Flow Updates, this webhook will fire when an update detects a new loan payment. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights.

#### Properties 

**webhook\_type** (string)  
CASH\_FLOW\_UPDATES

**webhook\_code** (string)  
NEW\_LOAN\_PAYMENT\_DETECTED

**status** (string)  
Enum for the status of the insights Possible values: AVAILABLE, FAILED

**user\_id** (string)  
The user\_id that the report is associated with

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CASH_FLOW_UPDATES",
  "webhook_code": "NEW_LOAN_PAYMENT_DETECTED",
  "status": "AVAILABLE",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "environment": "production"
}
```

\=\*=\*=\*=

#### NSF\_OVERDRAFT\_DETECTED 

For each user's item enabled for Cash Flow Updates, this webhook will fire when an update includes an NSF overdraft transaction. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights.

#### Properties 

**webhook\_type** (string)  
CASH\_FLOW\_UPDATES

**webhook\_code** (string)  
NSF\_OVERDRAFT\_DETECTED

**status** (string)  
Enum for the status of the insights Possible values: AVAILABLE, FAILED

**user\_id** (string)  
The user\_id that the report is associated with

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "CASH_FLOW_UPDATES",
  "webhook_code": "NSF_OVERDRAFT_DETECTED",
  "status": "AVAILABLE",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "environment": "production"
}
```

---


# API - Enrich | Plaid Docs

Enrich 
=======

#### API reference for Enrich endpoint 

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

| Endpoints |  |
| --- | --- |
| [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) | Send transaction data and retrieve enrichments |

\=\*=\*=\*=

#### /transactions/enrich 

#### Enrich locally-held transaction data 

The [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) endpoint enriches raw transaction data generated by your own banking products or retrieved from other non-Plaid sources.

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

**account\_type** (required, string)  
The account type for the requested transactions (either depository or credit).

**transactions** (required, \[object\])  
An array of transaction objects to be enriched by Plaid. Maximum of 100 transactions per request.

**transactions->id** (required, string)  
A unique ID for the transaction used to help you tie data back to your systems.

**transactions->description** (required, string)  
The raw description of the transaction. If you have location data in available an unstructured format, it may be appended to the description field.

**transactions->amount** (required, number)  
The absolute value of the transaction (>= 0). When testing Enrich, note that amount data should be realistic. Unrealistic or inaccurate amount data may result in reduced quality output. Format: double

**transactions->direction** (required, string)  
The direction of the transaction from the perspective of the account holder: OUTFLOW - Includes outgoing transfers, purchases, and fees. (Typically represented as a negative value on checking accounts and debit cards and a positive value on credit cards.) INFLOW - Includes incoming transfers, refunds, and income. (Typically represented as a positive value on checking accounts and debit cards and a negative value on credit cards.) Possible values: INFLOW, OUTFLOW

**transactions->iso\_currency\_code** (required, string)  
The ISO-4217 currency code of the transaction e.g. USD.

**transactions->location** (object)  
A representation of where a transaction took place. Use this field to pass in structured location information you may have about your transactions. Providing location data is optional but can increase result quality. If you have unstructured location information, it may be appended to the description field.

**transactions->location->country** (string)  
The country where the transaction occurred.

**transactions->location->region** (string)  
The region or state where the transaction occurred.

**transactions->location->city** (string)  
The city where the transaction occurred.

**transactions->location->address** (string)  
The street address where the transaction occurred.

**transactions->location->postal\_code** (string)  
The postal code where the transaction occurred.

**transactions->mcc** (string)  
Merchant category codes (MCCs) are four-digit numbers that describe a merchant's primary business activities.

**transactions->date\_posted** (string)  
The date the transaction posted, in ISO 8601 (YYYY-MM-DD) format. Format: date

**options** (object)  
An optional object to be used with the request.

**options->include\_legacy\_category** (boolean)  
Include legacy\_category and legacy\_category\_id in the response (in addition to the default personal\_finance\_category). Categories are based on Plaid's legacy taxonomy. For a full list of legacy categories, see /categories/get. Default: false

```javascript
const transactionsToEnrich: Array = [
  {
    id: '1',
    description: 'PURCHASE WM SUPERCENTER #1700',
    amount: 72.1,
    iso_currency_code: 'USD',
    location: {
      city: 'Poway',
      region: 'CA',
    },
    direction: EnrichTransactionDirection.Outflow,
  },
  {
    id: '2',
    description: 'DD DOORDASH BURGERKIN 855-123-4567 CA',
    amount: 28.34,
    iso_currency_code: 'USD',
    direction: EnrichTransactionDirection.Outflow,
  },
];


const request: TransactionsEnrichRequest = {
  account_type: 'depository',
  transactions: transactionsToEnrich,
};


const response = await client.transactionsEnrich(request);
const enrichedTransactions = response.data.enriched_transactions;
```

#### Response fields and example 

**enriched\_transactions** (\[object\])  
A list of enriched transactions.

**enriched\_transactions->id** (string)  
The unique ID for the transaction as provided by you in the request.

**enriched\_transactions->description** (string)  
The raw description of the transaction.

**enriched\_transactions->amount** (number)  
The absolute value of the transaction (>= 0) Format: double

**enriched\_transactions->direction** (string)  
The direction of the transaction from the perspective of the account holder: OUTFLOW - Includes outgoing transfers, purchases, and fees. (Typically represented as a negative value on checking accounts and debit cards and a positive value on credit cards.) INFLOW - Includes incoming transfers, refunds, and income. (Typically represented as a positive value on checking accounts and debit cards and a negative value on credit cards.) Possible values: INFLOW, OUTFLOW

**enriched\_transactions->iso\_currency\_code** (string)  
The ISO-4217 currency code of the transaction e.g. USD.

**enriched\_transactions->enrichments** (object)  
A grouping of the Plaid produced transaction enrichment fields.

**enriched\_transactions->enrichments->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**enriched\_transactions->enrichments->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**enriched\_transactions->enrichments->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**enriched\_transactions->enrichments->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**enriched\_transactions->enrichments->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**enriched\_transactions->enrichments->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**enriched\_transactions->enrichments->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**enriched\_transactions->enrichments->counterparties->phone\_number** (nullable, string)  
The phone number associated with the counterparty in E. 164 format. If there is a location match (i.e. a street address is returned in the location object), the phone number will be location specific.

**enriched\_transactions->enrichments->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**enriched\_transactions->enrichments->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**enriched\_transactions->enrichments->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**enriched\_transactions->enrichments->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**enriched\_transactions->enrichments->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**enriched\_transactions->enrichments->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**enriched\_transactions->enrichments->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**enriched\_transactions->enrichments->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the primary counterparty.

**enriched\_transactions->enrichments->legacy\_category\_id** (deprecated, nullable, string)  
The ID of the legacy category to which this transaction belongs. For a full list of legacy categories, see /categories/get. We recommend using the personal\_finance\_category for transaction categorization to obtain the best results.

**enriched\_transactions->enrichments->legacy\_category** (deprecated, nullable, \[string\])  
A hierarchical array of the legacy categories to which this transaction belongs. For a full list of legacy categories, see /categories/get. We recommend using the personal\_finance\_category for transaction categorization to obtain the best results.

**enriched\_transactions->enrichments->location** (object)  
A representation of where a transaction took place

**enriched\_transactions->enrichments->location->address** (nullable, string)  
The street address where the transaction occurred.

**enriched\_transactions->enrichments->location->city** (nullable, string)  
The city where the transaction occurred.

**enriched\_transactions->enrichments->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**enriched\_transactions->enrichments->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**enriched\_transactions->enrichments->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**enriched\_transactions->enrichments->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**enriched\_transactions->enrichments->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**enriched\_transactions->enrichments->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**enriched\_transactions->enrichments->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**enriched\_transactions->enrichments->merchant\_name** (nullable, string)  
The name of the primary counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**enriched\_transactions->enrichments->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. Possible values: online, in store, other

**enriched\_transactions->enrichments->phone\_number** (nullable, string)  
The phone number associated with the counterparty in E. 164 format. If there is a location match (i.e. a street address is returned in the location object), the phone number will be location specific.

**enriched\_transactions->enrichments->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**enriched\_transactions->enrichments->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**enriched\_transactions->enrichments->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**enriched\_transactions->enrichments->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**enriched\_transactions->enrichments->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**enriched\_transactions->enrichments->recurrence** (nullable, object)  
Insights relating to expenses and deposits that are predicted to occur on a scheduled basis, such as biweekly, monthly, or annually. Common examples include loan payments, bill payments, subscriptions, and payroll income. This is a beta field, available to all users.

**enriched\_transactions->enrichments->recurrence->is\_recurring** (nullable, boolean)  
Whether or not the transaction is periodically recurring.

**enriched\_transactions->enrichments->website** (nullable, string)  
The website associated with this transaction.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "enriched_transactions": [
    {
      "id": "6135818adda16500147e7c1d",
      "description": "PURCHASE WM SUPERCENTER #1700",
      "amount": 72.1,
      "direction": "OUTFLOW",
      "iso_currency_code": "USD",
      "enrichments": {
        "counterparties": [
          {
            "name": "Walmart",
            "type": "merchant",
            "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
            "website": "walmart.com",
            "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
            "confidence_level": "VERY_HIGH",
            "phone_number": "+18009256278"
          }
        ],
        "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
        "location": {
          "address": "13425 Community Rd",
          "city": "Poway",
          "region": "CA",
          "postal_code": "92064",
          "country": "US",
          "store_number": "1700",
          "lat": 32.959068,
          "lon": -117.037666
        },
        "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
        "merchant_name": "Walmart",
        "payment_channel": "in store",
        "personal_finance_category": {
          "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
          "primary": "GENERAL_MERCHANDISE",
          "confidence_level": "VERY_HIGH"
        },
        "phone_number": "+18009256278",
        "recurrence": {
          "is_recurring": false
        },
        "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
        "website": "walmart.com"
      }
    },
    {
      "id": "3958434bhde9384bcmeo3401",
      "description": "DD DOORDASH BURGERKIN 855-123-4567 CA",
      "amount": 28.34,
      "direction": "OUTFLOW",
      "iso_currency_code": "USD",
      "enrichments": {
        "counterparties": [
          {
            "name": "DoorDash",
            "type": "marketplace",
            "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",
            "website": "doordash.com",
            "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",
            "confidence_level": "VERY_HIGH",
            "phone_number": "+18001234567"
          },
          {
            "name": "Burger King",
            "type": "merchant",
            "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
            "website": "burgerking.com",
            "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
            "confidence_level": "VERY_HIGH",
            "phone_number": null
          }
        ],
        "location": {
          "address": null,
          "city": null,
          "region": null,
          "postal_code": null,
          "country": null,
          "store_number": null,
          "lat": null,
          "lon": null
        },
        "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
        "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
        "merchant_name": "Burger King",
        "payment_channel": "online",
        "personal_finance_category": {
          "detailed": "FOOD_AND_DRINK_FAST_FOOD",
          "primary": "FOOD_AND_DRINK",
          "confidence_level": "VERY_HIGH"
        },
        "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",
        "phone_number": null,
        "recurrence": {
          "is_recurring": false
        },
        "website": "burgerking.com"
      }
    }
  ],
  "request_id": "Wvhy9PZHQLV8njG"
}
```

---


# API - Identity Verification | Plaid Docs

Identity Verification 
======================

#### API reference for Identity Verification endpoints and webhooks 

For how-to guidance, see the [Identity Verification documentation](https://plaid.com/docs/identity-verification/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) | Create a new identity verification |
| [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) | Retrieve a previously created identity verification |
| [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) | Filter and list identity verifications |
| [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) | Allow a user to retry an identity verification |

| See also |  |
| --- | --- |
| [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user |
| [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users |

| Webhooks |  |
| --- | --- |
| [STATUS\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#status_updated) | The status of an identity verification has been updated |
| [STEP\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#step_updated) | A step in the identity verification process has been completed |
| [RETRIED](https://plaid.com/docs/api/products/identity-verification/index.html.md#retried) | An identity verification has been retried |

### Endpoints 

\=\*=\*=\*=

#### /identity\_verification/create 

#### Create a new Identity Verification 

Create a new Identity Verification for the user specified by the `client_user_id` and/or `user_id` field. At least one of these two fields must be provided. The requirements and behavior of the verification are determined by the `template_id` provided. If `user_id` is provided, there must be an associated user otherwise an error will be returned. If you don't know whether an active Identity Verification exists for a given `client_user_id` and/or `user_id`, you can specify `"is_idempotent": true` in the request body. With idempotency enabled, a new Identity Verification will only be created if one does not already exist for the associated `client_user_id` and/or `user_id`, and `template_id`. If an Identity Verification is found, it will be returned unmodified with a `200 OK` HTTP status code. If `user_id` is not provided, you can also use this endpoint to supply information you already have collected about the user; if any of these fields are specified, the screens prompting the user to enter them will be skipped during the Link flow. If `user_id` is provided, user information can not be included in the request body. Please use the [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) endpoint to update user data instead.

#### Request fields 

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**user\_id** (string)  
A unique user\_id generated by Plaid for the client-provided client\_user\_id. This field is currently in beta.

**is\_shareable** (required, boolean)  
A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created.

**template\_id** (required, string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**gave\_consent** (required, boolean)  
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes. If gave\_consent is set to true, the accept\_tos step will be marked as skipped and the end user's session will start at the next step requirement. Default: false

**user** (object)  
User information collected outside of Link, most likely via your own onboarding process. Each of the following identity fields are optional: email\_address phone\_number date\_of\_birth name address id\_number Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the accept\_tos step, depending on the value provided to the gave\_consent field. If you are not using the shareable URL feature, you can optionally provide these fields via /link/token/create instead; both /identity\_verification/create and /link/token/create are valid ways to provide this information. Note that if you provide a non-null user data object via /identity\_verification/create, any user data fields entered via /link/token/create for the same client\_user\_id will be ignored when prefilling Link.

**user->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (string)  
A valid phone number in E.164 format.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (object)  
You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the identity verification attempt.

**user->name->given\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Home address for the user. Supported values are: not provided, address with only country code or full address. For more context on this field, see Input Validation by Country.

**user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (required, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->id\_number** (object)  
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->id\_number->value** (required, string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (required, string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**user->client\_user\_id** (deprecated, string)  
Specifying user.client\_user\_id is deprecated. Please provide client\_user\_id at the root level instead.

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

**is\_idempotent** (boolean)  
An optional flag specifying how you would like Plaid to handle attempts to create an Identity Verification when an Identity Verification already exists for the provided client\_user\_id and template\_id. If idempotency is enabled, Plaid will return the existing Identity Verification. If idempotency is disabled, Plaid will reject the request with a 400 Bad Request status code if an Identity Verification already exists for the supplied client\_user\_id and template\_id.

```javascript
const request: IdentityVerificationCreateRequest = {
  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
  is_shareable: true,
  template_id: 'idvtmp_52xR9LKo77r1Np',
  gave_consent: true,
  user: {
    email_address: 'acharleston@email.com',
    phone_number: '+12345678909',
    date_of_birth: '1975-01-18',
    name: {
      given_name: 'Anna',
      family_name: 'Charleston',
    },
    address: {
      street: '100 Market Street',
      street2: 'Apt 1A',
      city: 'San Francisco',
      region: 'CA',
      postal_code: '94103',
      country: 'US',
    },
    id_number: {
      value: '123456789',
      type: 'us_ssn',
    },
  },
};
try {
  const response = await client.identityVerificationCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Identity Verification attempt.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**completed\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**previous\_attempt\_id** (nullable, string)  
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.

**shareable\_url** (nullable, string)  
A shareable URL that can be sent directly to the user to complete verification

**template** (object)  
The resource ID and version number of the template configuring the behavior of a given Identity Verification.

**template->id** (string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**template->version** (integer)  
Version of the associated Identity Verification template.

**user** (object)  
The identity data that was either collected from the user or provided via API in order to perform an Identity Verification.

**user->phone\_number** (nullable, string)  
A valid phone number in E.164 format.

**user->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

**user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->name** (nullable, object)  
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (nullable, object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code

**user->address->street** (nullable, string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (nullable, string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->id\_number** (nullable, object)  
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**status** (string)  
The status of this Identity Verification attempt. active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template failed - The user failed one or more steps in the session and was told to contact support. expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: active, success, failed, expired, canceled, pending\_review

**steps** (object)  
Each step will be one of the following values: active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point. success - The Identity Verification attempt has completed this step. failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. waiting\_for\_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. not\_applicable - This step will not be run for this session. skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. expired - This step had not yet been completed when the Identity Verification attempt as a whole expired. canceled - The Identity Verification attempt was canceled before the user completed this step. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. manually\_approved - The step was manually overridden to pass by a team member in the dashboard. manually\_rejected - The step was manually overridden to fail by a team member in the dashboard.

**steps->accept\_tos** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->verify\_sms** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->kyc\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->documentary\_verification** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->selfie\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->watchlist\_screening** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->risk\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**documentary\_verification** (nullable, object)  
Data, images, analysis, and results from the documentary\_verification step. This field will be null unless steps.documentary\_verification has reached a terminal state of either success or failed.

**documentary\_verification->status** (string)  
The outcome status for the associated Identity Verification attempt's documentary\_verification step. This field will always have the same value as steps.documentary\_verification.

**documentary\_verification->documents** (\[object\])  
An array of documents submitted to the documentary\_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary\_verification is failed, the user has exhausted their retry attempts.

**documentary\_verification->documents->status** (string)  
An outcome status for this specific document submission. Distinct from the overall documentary\_verification.status that summarizes the verification outcome from one or more documents. Possible values: success, failed, manually\_approved

**documentary\_verification->documents->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent document upload.

**documentary\_verification->documents->images** (object)  
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.

**documentary\_verification->documents->images->original\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

**documentary\_verification->documents->images->original\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

**documentary\_verification->documents->images->cropped\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

**documentary\_verification->documents->images->cropped\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

**documentary\_verification->documents->images->face** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

**documentary\_verification->documents->extracted\_data** (nullable, object)  
Data extracted from a user-submitted document.

**documentary\_verification->documents->extracted\_data->id\_number** (nullable, string)  
Alpha-numeric ID number extracted via OCR from the user's document image.

**documentary\_verification->documents->extracted\_data->category** (string)  
The type of identity document detected in the images provided. Will always be one of the following values: drivers\_license - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges id\_card - A general national identification card, distinct from driver's licenses as it only establishes identity passport - A travel passport issued by the associated country for one of its citizens residence\_permit\_card - An identity document issued by the associated country permitting a foreign citizen to temporarily reside there resident\_card - An identity document issued by the associated country permitting a foreign citizen to permanently reside there visa - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport Possible values: drivers\_license, id\_card, passport, residence\_permit\_card, resident\_card, visa

**documentary\_verification->documents->extracted\_data->expiration\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**documentary\_verification->documents->extracted\_data->issuing\_country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**documentary\_verification->documents->extracted\_data->issuing\_region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**documentary\_verification->documents->extracted\_data->date\_of\_birth** (nullable, string)  
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**documentary\_verification->documents->extracted\_data->address** (nullable, object)  
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null. region, and postal\_code may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.

**documentary\_verification->documents->extracted\_data->address->street** (string)  
The full street address extracted from the document.

**documentary\_verification->documents->extracted\_data->address->city** (string)  
City extracted from the document.

**documentary\_verification->documents->extracted\_data->address->region** (nullable, string)  
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**documentary\_verification->documents->extracted\_data->address->postal\_code** (nullable, string)  
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**documentary\_verification->documents->extracted\_data->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

**documentary\_verification->documents->extracted\_data->name** (nullable, object)  
The individual's name extracted from the document.

**documentary\_verification->documents->extracted\_data->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**documentary\_verification->documents->extracted\_data->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**documentary\_verification->documents->analysis** (object)  
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

**documentary\_verification->documents->analysis->authenticity** (string)  
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->image\_quality** (string)  
A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: high, medium, low

**documentary\_verification->documents->analysis->extracted\_data** (nullable, object)  
Analysis of the data extracted from the submitted document.

**documentary\_verification->documents->analysis->extracted\_data->name** (string)  
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->extracted\_data->date\_of\_birth** (string)  
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->extracted\_data->expiration\_date** (string)  
A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no\_data. Possible values: not\_expired, expired, no\_data

**documentary\_verification->documents->analysis->extracted\_data->issuing\_country** (string)  
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a no\_match on issuing\_country fails the documentary\_verification by editing your Plaid Template. Possible values: match, no\_match

**documentary\_verification->documents->analysis->aamva\_verification** (nullable, object)  
Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states.

**documentary\_verification->documents->analysis->aamva\_verification->is\_verified** (boolean)  
The overall outcome of checking the associated hit against the issuing state database.

**documentary\_verification->documents->analysis->aamva\_verification->id\_number** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->id\_issue\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->id\_expiration\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->street** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->city** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->postal\_code** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->date\_of\_birth** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->gender** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->height** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->eye\_color** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->first\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->middle\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->last\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**selfie\_check** (nullable, object)  
Additional information for the selfie\_check step. This field will be null unless steps.selfie\_check has reached a terminal state of either success or failed.

**selfie\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's selfie\_check step. This field will always have the same value as steps.selfie\_check. Possible values: success, failed

**selfie\_check->selfies** (\[object\])  
An array of selfies submitted to the selfie\_check step. Each entry represents one user submission.

**selfie\_check->selfies->status** (string)  
An outcome status for this specific selfie. Distinct from the overall selfie\_check.status that summarizes the verification outcome from one or more selfies. Possible values: success, failed

**selfie\_check->selfies->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent selfie upload.

**selfie\_check->selfies->capture** (object)  
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

**selfie\_check->selfies->capture->image\_url** (nullable, string)  
Temporary URL for downloading an image selfie capture.

**selfie\_check->selfies->capture->video\_url** (nullable, string)  
Temporary URL for downloading a video selfie capture.

**selfie\_check->selfies->analysis** (object)  
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

**selfie\_check->selfies->analysis->document\_comparison** (string)  
Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: match, no\_match, no\_input

**selfie\_check->selfies->analysis->liveness\_check** (string)  
Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: success, failed

**kyc\_check** (nullable, object)  
Additional information for the kyc\_check (Data Source Verification) step. This field will be null unless steps.kyc\_check has reached a terminal state of either success or failed.

**kyc\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's kyc\_check step. This field will always have the same value as steps.kyc\_check.

**kyc\_check->address** (object)  
Result summary object specifying how the address field matched.

**kyc\_check->address->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->address->po\_box** (string)  
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no\_data when Plaid was not able to determine if the address is a P.O. box. Possible values: yes, no, no\_data

**kyc\_check->address->type** (string)  
Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be no\_data when Plaid does not have sufficient data to determine the address's use. Possible values: residential, commercial, no\_data

**kyc\_check->name** (object)  
Result summary object specifying how the name field matched.

**kyc\_check->name->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->date\_of\_birth** (object)  
Result summary object specifying how the date\_of\_birth field matched.

**kyc\_check->date\_of\_birth->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->id\_number** (object)  
Result summary object specifying how the id\_number field matched.

**kyc\_check->id\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->phone\_number** (object)  
Result summary object specifying how the phone field matched.

**kyc\_check->phone\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->phone\_number->area\_code** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**risk\_check** (nullable, object)  
Additional information for the risk\_check step.

**risk\_check->status** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**risk\_check->behavior** (nullable, object)  
Result summary object specifying values for behavior attributes of risk check, when available.

**risk\_check->behavior->user\_interactions** (string)  
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome. risky indicates the user has low familiarity with the data they are providing, and that fraud is likely. no\_data indicates there is not sufficient information to give an accurate signal. Possible values: genuine, neutral, risky, no\_data

**risk\_check->behavior->fraud\_ring\_detected** (string)  
Field describing the outcome of a fraud ring behavior risk check. yes indicates that fraud ring activity was detected. no indicates that fraud ring activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**risk\_check->behavior->bot\_detected** (string)  
Field describing the outcome of a bot detection behavior risk check. yes indicates that automated activity was detected. no indicates that automated activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**risk\_check->email** (nullable, object)  
Result summary object specifying values for email attributes of risk check.

**risk\_check->email->is\_deliverable** (string)  
SMTP-MX check to confirm the email address exists if known. Possible values: yes, no, no\_data

**risk\_check->email->breach\_count** (nullable, integer)  
Count of all known breaches of this email address if known.

**risk\_check->email->first\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->last\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->domain\_registered\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->domain\_is\_free\_provider** (string)  
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: yes, no, no\_data

**risk\_check->email->domain\_is\_custom** (string)  
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: yes, no, no\_data

**risk\_check->email->domain\_is\_disposable** (string)  
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: yes, no, no\_data

**risk\_check->email->top\_level\_domain\_is\_suspicious** (string)  
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: yes, no, no\_data

**risk\_check->email->linked\_services** (\[string\])  
A list of online services where this email address has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**risk\_check->phone** (nullable, object)  
Result summary object specifying values for phone attributes of risk check.

**risk\_check->phone->linked\_services** (\[string\])  
A list of online services where this phone number has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**risk\_check->devices** (\[object\])  
Array of result summary objects specifying values for device attributes of risk check.

**risk\_check->devices->ip\_proxy\_type** (nullable, string)  
An enum indicating whether a network proxy is present and if so what type it is. none\_detected indicates the user is not on a detectable proxy network. tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). vpn indicates the user is on a VPN (Virtual Private Network) web\_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. public\_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: none\_detected, tor, vpn, web\_proxy, public\_proxy

**risk\_check->devices->ip\_spam\_list\_count** (nullable, integer)  
Count of spam lists the IP address is associated with if known.

**risk\_check->devices->ip\_timezone\_offset** (nullable, string)  
UTC offset of the timezone associated with the IP address.

**risk\_check->identity\_abuse\_signals** (nullable, object)  
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.

**risk\_check->identity\_abuse\_signals->synthetic\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**risk\_check->identity\_abuse\_signals->synthetic\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**risk\_check->identity\_abuse\_signals->stolen\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**risk\_check->identity\_abuse\_signals->stolen\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**verify\_sms** (nullable, object)  
Additional information for the verify\_sms step.

**verify\_sms->status** (string)  
The outcome status for the associated Identity Verification attempt's verify\_sms step. This field will always have the same value as steps.verify\_sms. Possible values: success, failed

**verify\_sms->verifications** (\[object\])  
An array where each entry represents a verification attempt for the verify\_sms step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.

**verify\_sms->verifications->status** (string)  
The outcome status for the individual SMS verification. Possible values: pending, success, failed, canceled

**verify\_sms->verifications->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent SMS verification.

**verify\_sms->verifications->phone\_number** (nullable, string)  
A phone number in E.164 format.

**verify\_sms->verifications->delivery\_attempt\_count** (integer)  
The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification.

**verify\_sms->verifications->solve\_attempt\_count** (integer)  
The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification.

**verify\_sms->verifications->initially\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**verify\_sms->verifications->last\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**verify\_sms->verifications->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_screening\_id** (nullable, string)  
ID of the associated screening.

**beacon\_user\_id** (nullable, string)  
ID of the associated Beacon User.

**user\_id** (nullable, string)  
A unique user\_id generated by Plaid for the client-provided client\_user\_id. This field is currently in beta.

**redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "idv_52xR9LKo77r1Np",
  "client_user_id": "your-db-id-3b24110",
  "created_at": "2020-07-24T03:26:02Z",
  "completed_at": "2020-07-24T03:26:02Z",
  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
  "template": {
    "id": "idvtmp_4FrXJvfQU3zGUR",
    "version": 2
  },
  "user": {
    "phone_number": "+12345678909",
    "date_of_birth": "1990-05-29",
    "ip_address": "192.0.2.42",
    "email_address": "user@example.com",
    "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"
    }
  },
  "status": "success",
  "steps": {
    "accept_tos": "success",
    "verify_sms": "success",
    "kyc_check": "success",
    "documentary_verification": "success",
    "selfie_check": "success",
    "watchlist_screening": "success",
    "risk_check": "success"
  },
  "documentary_verification": {
    "status": "success",
    "documents": [
      {
        "status": "success",
        "attempt": 1,
        "images": {
          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
        },
        "extracted_data": {
          "id_number": "AB123456",
          "category": "drivers_license",
          "expiration_date": "1990-05-29",
          "issuing_country": "US",
          "issuing_region": "IN",
          "date_of_birth": "1990-05-29",
          "address": {
            "street": "123 Main St. Unit 42",
            "city": "Pawnee",
            "region": "IN",
            "postal_code": "46001",
            "country": "US"
          },
          "name": {
            "given_name": "Leslie",
            "family_name": "Knope"
          }
        },
        "analysis": {
          "authenticity": "match",
          "image_quality": "high",
          "extracted_data": {
            "name": "match",
            "date_of_birth": "match",
            "expiration_date": "not_expired",
            "issuing_country": "match"
          },
          "aamva_verification": {
            "is_verified": true,
            "id_number": "match",
            "id_issue_date": "match",
            "id_expiration_date": "match",
            "street": "match",
            "city": "match",
            "postal_code": "match",
            "date_of_birth": "match",
            "gender": "match",
            "height": "match",
            "eye_color": "match",
            "first_name": "match",
            "middle_name": "match",
            "last_name": "match"
          }
        },
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "selfie_check": {
    "status": "success",
    "selfies": [
      {
        "status": "success",
        "attempt": 1,
        "capture": {
          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
        },
        "analysis": {
          "document_comparison": "match",
          "liveness_check": "success"
        }
      }
    ]
  },
  "kyc_check": {
    "status": "success",
    "address": {
      "summary": "match",
      "po_box": "yes",
      "type": "residential"
    },
    "name": {
      "summary": "match"
    },
    "date_of_birth": {
      "summary": "match"
    },
    "id_number": {
      "summary": "match"
    },
    "phone_number": {
      "summary": "match",
      "area_code": "match"
    }
  },
  "risk_check": {
    "status": "success",
    "behavior": {
      "user_interactions": "risky",
      "fraud_ring_detected": "yes",
      "bot_detected": "yes"
    },
    "email": {
      "is_deliverable": "yes",
      "breach_count": 1,
      "first_breached_at": "1990-05-29",
      "last_breached_at": "1990-05-29",
      "domain_registered_at": "1990-05-29",
      "domain_is_free_provider": "yes",
      "domain_is_custom": "yes",
      "domain_is_disposable": "yes",
      "top_level_domain_is_suspicious": "yes",
      "linked_services": [
        "apple"
      ]
    },
    "phone": {
      "linked_services": [
        "apple"
      ]
    },
    "devices": [
      {
        "ip_proxy_type": "none_detected",
        "ip_spam_list_count": 1,
        "ip_timezone_offset": "+06:00:00"
      }
    ],
    "identity_abuse_signals": {
      "synthetic_identity": {
        "score": 0
      },
      "stolen_identity": {
        "score": 0
      }
    }
  },
  "verify_sms": {
    "status": "success",
    "verifications": [
      {
        "status": "success",
        "attempt": 1,
        "phone_number": "+12345678909",
        "delivery_attempt_count": 1,
        "solve_attempt_count": 1,
        "initially_sent_at": "2020-07-24T03:26:02Z",
        "last_sent_at": "2020-07-24T03:26:02Z",
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "user_id": "usr_dddAs9ewdcDQQQ",
  "redacted_at": "2020-07-24T03:26:02Z",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /identity\_verification/get 

#### Retrieve Identity Verification 

Retrieve a previously created Identity Verification.

#### Request fields 

**identity\_verification\_id** (required, string)  
ID of the associated Identity Verification attempt.

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

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

```javascript
const request: IdentityVerificationGetRequest = {
  identity_verification_id: 'idv_52xR9LKo77r1Np',
};
try {
  const response = await plaidClient.identityVerificationGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Identity Verification attempt.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**completed\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**previous\_attempt\_id** (nullable, string)  
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.

**shareable\_url** (nullable, string)  
A shareable URL that can be sent directly to the user to complete verification

**template** (object)  
The resource ID and version number of the template configuring the behavior of a given Identity Verification.

**template->id** (string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**template->version** (integer)  
Version of the associated Identity Verification template.

**user** (object)  
The identity data that was either collected from the user or provided via API in order to perform an Identity Verification.

**user->phone\_number** (nullable, string)  
A valid phone number in E.164 format.

**user->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

**user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->name** (nullable, object)  
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (nullable, object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code

**user->address->street** (nullable, string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (nullable, string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->id\_number** (nullable, object)  
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**status** (string)  
The status of this Identity Verification attempt. active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template failed - The user failed one or more steps in the session and was told to contact support. expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: active, success, failed, expired, canceled, pending\_review

**steps** (object)  
Each step will be one of the following values: active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point. success - The Identity Verification attempt has completed this step. failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. waiting\_for\_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. not\_applicable - This step will not be run for this session. skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. expired - This step had not yet been completed when the Identity Verification attempt as a whole expired. canceled - The Identity Verification attempt was canceled before the user completed this step. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. manually\_approved - The step was manually overridden to pass by a team member in the dashboard. manually\_rejected - The step was manually overridden to fail by a team member in the dashboard.

**steps->accept\_tos** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->verify\_sms** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->kyc\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->documentary\_verification** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->selfie\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->watchlist\_screening** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->risk\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**documentary\_verification** (nullable, object)  
Data, images, analysis, and results from the documentary\_verification step. This field will be null unless steps.documentary\_verification has reached a terminal state of either success or failed.

**documentary\_verification->status** (string)  
The outcome status for the associated Identity Verification attempt's documentary\_verification step. This field will always have the same value as steps.documentary\_verification.

**documentary\_verification->documents** (\[object\])  
An array of documents submitted to the documentary\_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary\_verification is failed, the user has exhausted their retry attempts.

**documentary\_verification->documents->status** (string)  
An outcome status for this specific document submission. Distinct from the overall documentary\_verification.status that summarizes the verification outcome from one or more documents. Possible values: success, failed, manually\_approved

**documentary\_verification->documents->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent document upload.

**documentary\_verification->documents->images** (object)  
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.

**documentary\_verification->documents->images->original\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

**documentary\_verification->documents->images->original\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

**documentary\_verification->documents->images->cropped\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

**documentary\_verification->documents->images->cropped\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

**documentary\_verification->documents->images->face** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

**documentary\_verification->documents->extracted\_data** (nullable, object)  
Data extracted from a user-submitted document.

**documentary\_verification->documents->extracted\_data->id\_number** (nullable, string)  
Alpha-numeric ID number extracted via OCR from the user's document image.

**documentary\_verification->documents->extracted\_data->category** (string)  
The type of identity document detected in the images provided. Will always be one of the following values: drivers\_license - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges id\_card - A general national identification card, distinct from driver's licenses as it only establishes identity passport - A travel passport issued by the associated country for one of its citizens residence\_permit\_card - An identity document issued by the associated country permitting a foreign citizen to temporarily reside there resident\_card - An identity document issued by the associated country permitting a foreign citizen to permanently reside there visa - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport Possible values: drivers\_license, id\_card, passport, residence\_permit\_card, resident\_card, visa

**documentary\_verification->documents->extracted\_data->expiration\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**documentary\_verification->documents->extracted\_data->issuing\_country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**documentary\_verification->documents->extracted\_data->issuing\_region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**documentary\_verification->documents->extracted\_data->date\_of\_birth** (nullable, string)  
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**documentary\_verification->documents->extracted\_data->address** (nullable, object)  
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null. region, and postal\_code may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.

**documentary\_verification->documents->extracted\_data->address->street** (string)  
The full street address extracted from the document.

**documentary\_verification->documents->extracted\_data->address->city** (string)  
City extracted from the document.

**documentary\_verification->documents->extracted\_data->address->region** (nullable, string)  
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**documentary\_verification->documents->extracted\_data->address->postal\_code** (nullable, string)  
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**documentary\_verification->documents->extracted\_data->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

**documentary\_verification->documents->extracted\_data->name** (nullable, object)  
The individual's name extracted from the document.

**documentary\_verification->documents->extracted\_data->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**documentary\_verification->documents->extracted\_data->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**documentary\_verification->documents->analysis** (object)  
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

**documentary\_verification->documents->analysis->authenticity** (string)  
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->image\_quality** (string)  
A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: high, medium, low

**documentary\_verification->documents->analysis->extracted\_data** (nullable, object)  
Analysis of the data extracted from the submitted document.

**documentary\_verification->documents->analysis->extracted\_data->name** (string)  
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->extracted\_data->date\_of\_birth** (string)  
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->extracted\_data->expiration\_date** (string)  
A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no\_data. Possible values: not\_expired, expired, no\_data

**documentary\_verification->documents->analysis->extracted\_data->issuing\_country** (string)  
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a no\_match on issuing\_country fails the documentary\_verification by editing your Plaid Template. Possible values: match, no\_match

**documentary\_verification->documents->analysis->aamva\_verification** (nullable, object)  
Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states.

**documentary\_verification->documents->analysis->aamva\_verification->is\_verified** (boolean)  
The overall outcome of checking the associated hit against the issuing state database.

**documentary\_verification->documents->analysis->aamva\_verification->id\_number** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->id\_issue\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->id\_expiration\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->street** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->city** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->postal\_code** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->date\_of\_birth** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->gender** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->height** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->eye\_color** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->first\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->middle\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->last\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**selfie\_check** (nullable, object)  
Additional information for the selfie\_check step. This field will be null unless steps.selfie\_check has reached a terminal state of either success or failed.

**selfie\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's selfie\_check step. This field will always have the same value as steps.selfie\_check. Possible values: success, failed

**selfie\_check->selfies** (\[object\])  
An array of selfies submitted to the selfie\_check step. Each entry represents one user submission.

**selfie\_check->selfies->status** (string)  
An outcome status for this specific selfie. Distinct from the overall selfie\_check.status that summarizes the verification outcome from one or more selfies. Possible values: success, failed

**selfie\_check->selfies->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent selfie upload.

**selfie\_check->selfies->capture** (object)  
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

**selfie\_check->selfies->capture->image\_url** (nullable, string)  
Temporary URL for downloading an image selfie capture.

**selfie\_check->selfies->capture->video\_url** (nullable, string)  
Temporary URL for downloading a video selfie capture.

**selfie\_check->selfies->analysis** (object)  
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

**selfie\_check->selfies->analysis->document\_comparison** (string)  
Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: match, no\_match, no\_input

**selfie\_check->selfies->analysis->liveness\_check** (string)  
Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: success, failed

**kyc\_check** (nullable, object)  
Additional information for the kyc\_check (Data Source Verification) step. This field will be null unless steps.kyc\_check has reached a terminal state of either success or failed.

**kyc\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's kyc\_check step. This field will always have the same value as steps.kyc\_check.

**kyc\_check->address** (object)  
Result summary object specifying how the address field matched.

**kyc\_check->address->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->address->po\_box** (string)  
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no\_data when Plaid was not able to determine if the address is a P.O. box. Possible values: yes, no, no\_data

**kyc\_check->address->type** (string)  
Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be no\_data when Plaid does not have sufficient data to determine the address's use. Possible values: residential, commercial, no\_data

**kyc\_check->name** (object)  
Result summary object specifying how the name field matched.

**kyc\_check->name->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->date\_of\_birth** (object)  
Result summary object specifying how the date\_of\_birth field matched.

**kyc\_check->date\_of\_birth->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->id\_number** (object)  
Result summary object specifying how the id\_number field matched.

**kyc\_check->id\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->phone\_number** (object)  
Result summary object specifying how the phone field matched.

**kyc\_check->phone\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->phone\_number->area\_code** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**risk\_check** (nullable, object)  
Additional information for the risk\_check step.

**risk\_check->status** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**risk\_check->behavior** (nullable, object)  
Result summary object specifying values for behavior attributes of risk check, when available.

**risk\_check->behavior->user\_interactions** (string)  
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome. risky indicates the user has low familiarity with the data they are providing, and that fraud is likely. no\_data indicates there is not sufficient information to give an accurate signal. Possible values: genuine, neutral, risky, no\_data

**risk\_check->behavior->fraud\_ring\_detected** (string)  
Field describing the outcome of a fraud ring behavior risk check. yes indicates that fraud ring activity was detected. no indicates that fraud ring activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**risk\_check->behavior->bot\_detected** (string)  
Field describing the outcome of a bot detection behavior risk check. yes indicates that automated activity was detected. no indicates that automated activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**risk\_check->email** (nullable, object)  
Result summary object specifying values for email attributes of risk check.

**risk\_check->email->is\_deliverable** (string)  
SMTP-MX check to confirm the email address exists if known. Possible values: yes, no, no\_data

**risk\_check->email->breach\_count** (nullable, integer)  
Count of all known breaches of this email address if known.

**risk\_check->email->first\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->last\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->domain\_registered\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->domain\_is\_free\_provider** (string)  
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: yes, no, no\_data

**risk\_check->email->domain\_is\_custom** (string)  
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: yes, no, no\_data

**risk\_check->email->domain\_is\_disposable** (string)  
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: yes, no, no\_data

**risk\_check->email->top\_level\_domain\_is\_suspicious** (string)  
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: yes, no, no\_data

**risk\_check->email->linked\_services** (\[string\])  
A list of online services where this email address has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**risk\_check->phone** (nullable, object)  
Result summary object specifying values for phone attributes of risk check.

**risk\_check->phone->linked\_services** (\[string\])  
A list of online services where this phone number has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**risk\_check->devices** (\[object\])  
Array of result summary objects specifying values for device attributes of risk check.

**risk\_check->devices->ip\_proxy\_type** (nullable, string)  
An enum indicating whether a network proxy is present and if so what type it is. none\_detected indicates the user is not on a detectable proxy network. tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). vpn indicates the user is on a VPN (Virtual Private Network) web\_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. public\_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: none\_detected, tor, vpn, web\_proxy, public\_proxy

**risk\_check->devices->ip\_spam\_list\_count** (nullable, integer)  
Count of spam lists the IP address is associated with if known.

**risk\_check->devices->ip\_timezone\_offset** (nullable, string)  
UTC offset of the timezone associated with the IP address.

**risk\_check->identity\_abuse\_signals** (nullable, object)  
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.

**risk\_check->identity\_abuse\_signals->synthetic\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**risk\_check->identity\_abuse\_signals->synthetic\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**risk\_check->identity\_abuse\_signals->stolen\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**risk\_check->identity\_abuse\_signals->stolen\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**verify\_sms** (nullable, object)  
Additional information for the verify\_sms step.

**verify\_sms->status** (string)  
The outcome status for the associated Identity Verification attempt's verify\_sms step. This field will always have the same value as steps.verify\_sms. Possible values: success, failed

**verify\_sms->verifications** (\[object\])  
An array where each entry represents a verification attempt for the verify\_sms step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.

**verify\_sms->verifications->status** (string)  
The outcome status for the individual SMS verification. Possible values: pending, success, failed, canceled

**verify\_sms->verifications->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent SMS verification.

**verify\_sms->verifications->phone\_number** (nullable, string)  
A phone number in E.164 format.

**verify\_sms->verifications->delivery\_attempt\_count** (integer)  
The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification.

**verify\_sms->verifications->solve\_attempt\_count** (integer)  
The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification.

**verify\_sms->verifications->initially\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**verify\_sms->verifications->last\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**verify\_sms->verifications->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_screening\_id** (nullable, string)  
ID of the associated screening.

**beacon\_user\_id** (nullable, string)  
ID of the associated Beacon User.

**user\_id** (nullable, string)  
A unique user\_id generated by Plaid for the client-provided client\_user\_id. This field is currently in beta.

**redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "idv_52xR9LKo77r1Np",
  "client_user_id": "your-db-id-3b24110",
  "created_at": "2020-07-24T03:26:02Z",
  "completed_at": "2020-07-24T03:26:02Z",
  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
  "template": {
    "id": "idvtmp_4FrXJvfQU3zGUR",
    "version": 2
  },
  "user": {
    "phone_number": "+12345678909",
    "date_of_birth": "1990-05-29",
    "ip_address": "192.0.2.42",
    "email_address": "user@example.com",
    "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"
    }
  },
  "status": "success",
  "steps": {
    "accept_tos": "success",
    "verify_sms": "success",
    "kyc_check": "success",
    "documentary_verification": "success",
    "selfie_check": "success",
    "watchlist_screening": "success",
    "risk_check": "success"
  },
  "documentary_verification": {
    "status": "success",
    "documents": [
      {
        "status": "success",
        "attempt": 1,
        "images": {
          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
        },
        "extracted_data": {
          "id_number": "AB123456",
          "category": "drivers_license",
          "expiration_date": "1990-05-29",
          "issuing_country": "US",
          "issuing_region": "IN",
          "date_of_birth": "1990-05-29",
          "address": {
            "street": "123 Main St. Unit 42",
            "city": "Pawnee",
            "region": "IN",
            "postal_code": "46001",
            "country": "US"
          },
          "name": {
            "given_name": "Leslie",
            "family_name": "Knope"
          }
        },
        "analysis": {
          "authenticity": "match",
          "image_quality": "high",
          "extracted_data": {
            "name": "match",
            "date_of_birth": "match",
            "expiration_date": "not_expired",
            "issuing_country": "match"
          },
          "aamva_verification": {
            "is_verified": true,
            "id_number": "match",
            "id_issue_date": "match",
            "id_expiration_date": "match",
            "street": "match",
            "city": "match",
            "postal_code": "match",
            "date_of_birth": "match",
            "gender": "match",
            "height": "match",
            "eye_color": "match",
            "first_name": "match",
            "middle_name": "match",
            "last_name": "match"
          }
        },
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "selfie_check": {
    "status": "success",
    "selfies": [
      {
        "status": "success",
        "attempt": 1,
        "capture": {
          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
        },
        "analysis": {
          "document_comparison": "match",
          "liveness_check": "success"
        }
      }
    ]
  },
  "kyc_check": {
    "status": "success",
    "address": {
      "summary": "match",
      "po_box": "yes",
      "type": "residential"
    },
    "name": {
      "summary": "match"
    },
    "date_of_birth": {
      "summary": "match"
    },
    "id_number": {
      "summary": "match"
    },
    "phone_number": {
      "summary": "match",
      "area_code": "match"
    }
  },
  "risk_check": {
    "status": "success",
    "behavior": {
      "user_interactions": "risky",
      "fraud_ring_detected": "yes",
      "bot_detected": "yes"
    },
    "email": {
      "is_deliverable": "yes",
      "breach_count": 1,
      "first_breached_at": "1990-05-29",
      "last_breached_at": "1990-05-29",
      "domain_registered_at": "1990-05-29",
      "domain_is_free_provider": "yes",
      "domain_is_custom": "yes",
      "domain_is_disposable": "yes",
      "top_level_domain_is_suspicious": "yes",
      "linked_services": [
        "apple"
      ]
    },
    "phone": {
      "linked_services": [
        "apple"
      ]
    },
    "devices": [
      {
        "ip_proxy_type": "none_detected",
        "ip_spam_list_count": 1,
        "ip_timezone_offset": "+06:00:00"
      }
    ],
    "identity_abuse_signals": {
      "synthetic_identity": {
        "score": 0
      },
      "stolen_identity": {
        "score": 0
      }
    }
  },
  "verify_sms": {
    "status": "success",
    "verifications": [
      {
        "status": "success",
        "attempt": 1,
        "phone_number": "+12345678909",
        "delivery_attempt_count": 1,
        "solve_attempt_count": 1,
        "initially_sent_at": "2020-07-24T03:26:02Z",
        "last_sent_at": "2020-07-24T03:26:02Z",
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "user_id": "usr_dddAs9ewdcDQQQ",
  "redacted_at": "2020-07-24T03:26:02Z",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /identity\_verification/list 

#### List Identity Verifications 

Filter and list Identity Verifications created by your account

#### Request fields 

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

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

**template\_id** (required, string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**user\_id** (string)  
A unique user\_id generated by Plaid for the client-provided client\_user\_id. This field is currently in beta. If both client\_user\_id and user\_id are provided, client\_user\_id must match the value for the returned user.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: ListIdentityVerificationRequest = {
  template_id: 'idvtmp_52xR9LKo77r1Np',
  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
};
try {
  const response = await plaidClient.identityVerificationList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**identity\_verifications** (\[object\])  
List of Plaid sessions

**identity\_verifications->id** (string)  
ID of the associated Identity Verification attempt.

**identity\_verifications->client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**identity\_verifications->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**identity\_verifications->completed\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**identity\_verifications->previous\_attempt\_id** (nullable, string)  
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.

**identity\_verifications->shareable\_url** (nullable, string)  
A shareable URL that can be sent directly to the user to complete verification

**identity\_verifications->template** (object)  
The resource ID and version number of the template configuring the behavior of a given Identity Verification.

**identity\_verifications->template->id** (string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**identity\_verifications->template->version** (integer)  
Version of the associated Identity Verification template.

**identity\_verifications->user** (object)  
The identity data that was either collected from the user or provided via API in order to perform an Identity Verification.

**identity\_verifications->user->phone\_number** (nullable, string)  
A valid phone number in E.164 format.

**identity\_verifications->user->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**identity\_verifications->user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

**identity\_verifications->user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**identity\_verifications->user->name** (nullable, object)  
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

**identity\_verifications->user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**identity\_verifications->user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**identity\_verifications->user->address** (nullable, object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code

**identity\_verifications->user->address->street** (nullable, string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**identity\_verifications->user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**identity\_verifications->user->address->city** (nullable, string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**identity\_verifications->user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**identity\_verifications->user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**identity\_verifications->user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**identity\_verifications->user->id\_number** (nullable, object)  
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

**identity\_verifications->user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**identity\_verifications->user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**identity\_verifications->status** (string)  
The status of this Identity Verification attempt. active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template failed - The user failed one or more steps in the session and was told to contact support. expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: active, success, failed, expired, canceled, pending\_review

**identity\_verifications->steps** (object)  
Each step will be one of the following values: active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point. success - The Identity Verification attempt has completed this step. failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. waiting\_for\_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. not\_applicable - This step will not be run for this session. skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. expired - This step had not yet been completed when the Identity Verification attempt as a whole expired. canceled - The Identity Verification attempt was canceled before the user completed this step. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. manually\_approved - The step was manually overridden to pass by a team member in the dashboard. manually\_rejected - The step was manually overridden to fail by a team member in the dashboard.

**identity\_verifications->steps->accept\_tos** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->steps->verify\_sms** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->steps->kyc\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->steps->documentary\_verification** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->steps->selfie\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->steps->watchlist\_screening** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->steps->risk\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->documentary\_verification** (nullable, object)  
Data, images, analysis, and results from the documentary\_verification step. This field will be null unless steps.documentary\_verification has reached a terminal state of either success or failed.

**identity\_verifications->documentary\_verification->status** (string)  
The outcome status for the associated Identity Verification attempt's documentary\_verification step. This field will always have the same value as steps.documentary\_verification.

**identity\_verifications->documentary\_verification->documents** (\[object\])  
An array of documents submitted to the documentary\_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary\_verification is failed, the user has exhausted their retry attempts.

**identity\_verifications->documentary\_verification->documents->status** (string)  
An outcome status for this specific document submission. Distinct from the overall documentary\_verification.status that summarizes the verification outcome from one or more documents. Possible values: success, failed, manually\_approved

**identity\_verifications->documentary\_verification->documents->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent document upload.

**identity\_verifications->documentary\_verification->documents->images** (object)  
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.

**identity\_verifications->documentary\_verification->documents->images->original\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

**identity\_verifications->documentary\_verification->documents->images->original\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

**identity\_verifications->documentary\_verification->documents->images->cropped\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

**identity\_verifications->documentary\_verification->documents->images->cropped\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

**identity\_verifications->documentary\_verification->documents->images->face** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

**identity\_verifications->documentary\_verification->documents->extracted\_data** (nullable, object)  
Data extracted from a user-submitted document.

**identity\_verifications->documentary\_verification->documents->extracted\_data->id\_number** (nullable, string)  
Alpha-numeric ID number extracted via OCR from the user's document image.

**identity\_verifications->documentary\_verification->documents->extracted\_data->category** (string)  
The type of identity document detected in the images provided. Will always be one of the following values: drivers\_license - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges id\_card - A general national identification card, distinct from driver's licenses as it only establishes identity passport - A travel passport issued by the associated country for one of its citizens residence\_permit\_card - An identity document issued by the associated country permitting a foreign citizen to temporarily reside there resident\_card - An identity document issued by the associated country permitting a foreign citizen to permanently reside there visa - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport Possible values: drivers\_license, id\_card, passport, residence\_permit\_card, resident\_card, visa

**identity\_verifications->documentary\_verification->documents->extracted\_data->expiration\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**identity\_verifications->documentary\_verification->documents->extracted\_data->issuing\_country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**identity\_verifications->documentary\_verification->documents->extracted\_data->issuing\_region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**identity\_verifications->documentary\_verification->documents->extracted\_data->date\_of\_birth** (nullable, string)  
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**identity\_verifications->documentary\_verification->documents->extracted\_data->address** (nullable, object)  
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null. region, and postal\_code may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.

**identity\_verifications->documentary\_verification->documents->extracted\_data->address->street** (string)  
The full street address extracted from the document.

**identity\_verifications->documentary\_verification->documents->extracted\_data->address->city** (string)  
City extracted from the document.

**identity\_verifications->documentary\_verification->documents->extracted\_data->address->region** (nullable, string)  
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**identity\_verifications->documentary\_verification->documents->extracted\_data->address->postal\_code** (nullable, string)  
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**identity\_verifications->documentary\_verification->documents->extracted\_data->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

**identity\_verifications->documentary\_verification->documents->extracted\_data->name** (nullable, object)  
The individual's name extracted from the document.

**identity\_verifications->documentary\_verification->documents->extracted\_data->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**identity\_verifications->documentary\_verification->documents->extracted\_data->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**identity\_verifications->documentary\_verification->documents->analysis** (object)  
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

**identity\_verifications->documentary\_verification->documents->analysis->authenticity** (string)  
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->image\_quality** (string)  
A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: high, medium, low

**identity\_verifications->documentary\_verification->documents->analysis->extracted\_data** (nullable, object)  
Analysis of the data extracted from the submitted document.

**identity\_verifications->documentary\_verification->documents->analysis->extracted\_data->name** (string)  
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->extracted\_data->date\_of\_birth** (string)  
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->extracted\_data->expiration\_date** (string)  
A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no\_data. Possible values: not\_expired, expired, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->extracted\_data->issuing\_country** (string)  
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a no\_match on issuing\_country fails the documentary\_verification by editing your Plaid Template. Possible values: match, no\_match

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification** (nullable, object)  
Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states.

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->is\_verified** (boolean)  
The overall outcome of checking the associated hit against the issuing state database.

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->id\_number** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->id\_issue\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->id\_expiration\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->street** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->city** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->postal\_code** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->date\_of\_birth** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->gender** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->height** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->eye\_color** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->first\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->middle\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->analysis->aamva\_verification->last\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**identity\_verifications->documentary\_verification->documents->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**identity\_verifications->selfie\_check** (nullable, object)  
Additional information for the selfie\_check step. This field will be null unless steps.selfie\_check has reached a terminal state of either success or failed.

**identity\_verifications->selfie\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's selfie\_check step. This field will always have the same value as steps.selfie\_check. Possible values: success, failed

**identity\_verifications->selfie\_check->selfies** (\[object\])  
An array of selfies submitted to the selfie\_check step. Each entry represents one user submission.

**identity\_verifications->selfie\_check->selfies->status** (string)  
An outcome status for this specific selfie. Distinct from the overall selfie\_check.status that summarizes the verification outcome from one or more selfies. Possible values: success, failed

**identity\_verifications->selfie\_check->selfies->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent selfie upload.

**identity\_verifications->selfie\_check->selfies->capture** (object)  
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

**identity\_verifications->selfie\_check->selfies->capture->image\_url** (nullable, string)  
Temporary URL for downloading an image selfie capture.

**identity\_verifications->selfie\_check->selfies->capture->video\_url** (nullable, string)  
Temporary URL for downloading a video selfie capture.

**identity\_verifications->selfie\_check->selfies->analysis** (object)  
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

**identity\_verifications->selfie\_check->selfies->analysis->document\_comparison** (string)  
Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: match, no\_match, no\_input

**identity\_verifications->selfie\_check->selfies->analysis->liveness\_check** (string)  
Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: success, failed

**identity\_verifications->kyc\_check** (nullable, object)  
Additional information for the kyc\_check (Data Source Verification) step. This field will be null unless steps.kyc\_check has reached a terminal state of either success or failed.

**identity\_verifications->kyc\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's kyc\_check step. This field will always have the same value as steps.kyc\_check.

**identity\_verifications->kyc\_check->address** (object)  
Result summary object specifying how the address field matched.

**identity\_verifications->kyc\_check->address->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**identity\_verifications->kyc\_check->address->po\_box** (string)  
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no\_data when Plaid was not able to determine if the address is a P.O. box. Possible values: yes, no, no\_data

**identity\_verifications->kyc\_check->address->type** (string)  
Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be no\_data when Plaid does not have sufficient data to determine the address's use. Possible values: residential, commercial, no\_data

**identity\_verifications->kyc\_check->name** (object)  
Result summary object specifying how the name field matched.

**identity\_verifications->kyc\_check->name->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**identity\_verifications->kyc\_check->date\_of\_birth** (object)  
Result summary object specifying how the date\_of\_birth field matched.

**identity\_verifications->kyc\_check->date\_of\_birth->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**identity\_verifications->kyc\_check->id\_number** (object)  
Result summary object specifying how the id\_number field matched.

**identity\_verifications->kyc\_check->id\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**identity\_verifications->kyc\_check->phone\_number** (object)  
Result summary object specifying how the phone field matched.

**identity\_verifications->kyc\_check->phone\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**identity\_verifications->kyc\_check->phone\_number->area\_code** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**identity\_verifications->risk\_check** (nullable, object)  
Additional information for the risk\_check step.

**identity\_verifications->risk\_check->status** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**identity\_verifications->risk\_check->behavior** (nullable, object)  
Result summary object specifying values for behavior attributes of risk check, when available.

**identity\_verifications->risk\_check->behavior->user\_interactions** (string)  
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome. risky indicates the user has low familiarity with the data they are providing, and that fraud is likely. no\_data indicates there is not sufficient information to give an accurate signal. Possible values: genuine, neutral, risky, no\_data

**identity\_verifications->risk\_check->behavior->fraud\_ring\_detected** (string)  
Field describing the outcome of a fraud ring behavior risk check. yes indicates that fraud ring activity was detected. no indicates that fraud ring activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->behavior->bot\_detected** (string)  
Field describing the outcome of a bot detection behavior risk check. yes indicates that automated activity was detected. no indicates that automated activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->email** (nullable, object)  
Result summary object specifying values for email attributes of risk check.

**identity\_verifications->risk\_check->email->is\_deliverable** (string)  
SMTP-MX check to confirm the email address exists if known. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->email->breach\_count** (nullable, integer)  
Count of all known breaches of this email address if known.

**identity\_verifications->risk\_check->email->first\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**identity\_verifications->risk\_check->email->last\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**identity\_verifications->risk\_check->email->domain\_registered\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**identity\_verifications->risk\_check->email->domain\_is\_free\_provider** (string)  
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->email->domain\_is\_custom** (string)  
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->email->domain\_is\_disposable** (string)  
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->email->top\_level\_domain\_is\_suspicious** (string)  
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: yes, no, no\_data

**identity\_verifications->risk\_check->email->linked\_services** (\[string\])  
A list of online services where this email address has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**identity\_verifications->risk\_check->phone** (nullable, object)  
Result summary object specifying values for phone attributes of risk check.

**identity\_verifications->risk\_check->phone->linked\_services** (\[string\])  
A list of online services where this phone number has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**identity\_verifications->risk\_check->devices** (\[object\])  
Array of result summary objects specifying values for device attributes of risk check.

**identity\_verifications->risk\_check->devices->ip\_proxy\_type** (nullable, string)  
An enum indicating whether a network proxy is present and if so what type it is. none\_detected indicates the user is not on a detectable proxy network. tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). vpn indicates the user is on a VPN (Virtual Private Network) web\_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. public\_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: none\_detected, tor, vpn, web\_proxy, public\_proxy

**identity\_verifications->risk\_check->devices->ip\_spam\_list\_count** (nullable, integer)  
Count of spam lists the IP address is associated with if known.

**identity\_verifications->risk\_check->devices->ip\_timezone\_offset** (nullable, string)  
UTC offset of the timezone associated with the IP address.

**identity\_verifications->risk\_check->identity\_abuse\_signals** (nullable, object)  
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.

**identity\_verifications->risk\_check->identity\_abuse\_signals->synthetic\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**identity\_verifications->risk\_check->identity\_abuse\_signals->synthetic\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**identity\_verifications->risk\_check->identity\_abuse\_signals->stolen\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**identity\_verifications->risk\_check->identity\_abuse\_signals->stolen\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**identity\_verifications->verify\_sms** (nullable, object)  
Additional information for the verify\_sms step.

**identity\_verifications->verify\_sms->status** (string)  
The outcome status for the associated Identity Verification attempt's verify\_sms step. This field will always have the same value as steps.verify\_sms. Possible values: success, failed

**identity\_verifications->verify\_sms->verifications** (\[object\])  
An array where each entry represents a verification attempt for the verify\_sms step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.

**identity\_verifications->verify\_sms->verifications->status** (string)  
The outcome status for the individual SMS verification. Possible values: pending, success, failed, canceled

**identity\_verifications->verify\_sms->verifications->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent SMS verification.

**identity\_verifications->verify\_sms->verifications->phone\_number** (nullable, string)  
A phone number in E.164 format.

**identity\_verifications->verify\_sms->verifications->delivery\_attempt\_count** (integer)  
The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification.

**identity\_verifications->verify\_sms->verifications->solve\_attempt\_count** (integer)  
The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification.

**identity\_verifications->verify\_sms->verifications->initially\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**identity\_verifications->verify\_sms->verifications->last\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**identity\_verifications->verify\_sms->verifications->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**identity\_verifications->watchlist\_screening\_id** (nullable, string)  
ID of the associated screening.

**identity\_verifications->beacon\_user\_id** (nullable, string)  
ID of the associated Beacon User.

**identity\_verifications->user\_id** (nullable, string)  
A unique user\_id generated by Plaid for the client-provided client\_user\_id. This field is currently in beta.

**identity\_verifications->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "identity_verifications": [
    {
      "id": "idv_52xR9LKo77r1Np",
      "client_user_id": "your-db-id-3b24110",
      "created_at": "2020-07-24T03:26:02Z",
      "completed_at": "2020-07-24T03:26:02Z",
      "previous_attempt_id": "idv_42cF1MNo42r9Xj",
      "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
      "template": {
        "id": "idvtmp_4FrXJvfQU3zGUR",
        "version": 2
      },
      "user": {
        "phone_number": "+12345678909",
        "date_of_birth": "1990-05-29",
        "ip_address": "192.0.2.42",
        "email_address": "user@example.com",
        "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"
        }
      },
      "status": "success",
      "steps": {
        "accept_tos": "success",
        "verify_sms": "success",
        "kyc_check": "success",
        "documentary_verification": "success",
        "selfie_check": "success",
        "watchlist_screening": "success",
        "risk_check": "success"
      },
      "documentary_verification": {
        "status": "success",
        "documents": [
          {
            "status": "success",
            "attempt": 1,
            "images": {
              "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
              "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
              "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
              "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
              "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
            },
            "extracted_data": {
              "id_number": "AB123456",
              "category": "drivers_license",
              "expiration_date": "1990-05-29",
              "issuing_country": "US",
              "issuing_region": "IN",
              "date_of_birth": "1990-05-29",
              "address": {
                "street": "123 Main St. Unit 42",
                "city": "Pawnee",
                "region": "IN",
                "postal_code": "46001",
                "country": "US"
              },
              "name": {
                "given_name": "Leslie",
                "family_name": "Knope"
              }
            },
            "analysis": {
              "authenticity": "match",
              "image_quality": "high",
              "extracted_data": {
                "name": "match",
                "date_of_birth": "match",
                "expiration_date": "not_expired",
                "issuing_country": "match"
              },
              "aamva_verification": {
                "is_verified": true,
                "id_number": "match",
                "id_issue_date": "match",
                "id_expiration_date": "match",
                "street": "match",
                "city": "match",
                "postal_code": "match",
                "date_of_birth": "match",
                "gender": "match",
                "height": "match",
                "eye_color": "match",
                "first_name": "match",
                "middle_name": "match",
                "last_name": "match"
              }
            },
            "redacted_at": "2020-07-24T03:26:02Z"
          }
        ]
      },
      "selfie_check": {
        "status": "success",
        "selfies": [
          {
            "status": "success",
            "attempt": 1,
            "capture": {
              "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
              "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
            },
            "analysis": {
              "document_comparison": "match",
              "liveness_check": "success"
            }
          }
        ]
      },
      "kyc_check": {
        "status": "success",
        "address": {
          "summary": "match",
          "po_box": "yes",
          "type": "residential"
        },
        "name": {
          "summary": "match"
        },
        "date_of_birth": {
          "summary": "match"
        },
        "id_number": {
          "summary": "match"
        },
        "phone_number": {
          "summary": "match",
          "area_code": "match"
        }
      },
      "risk_check": {
        "status": "success",
        "behavior": {
          "user_interactions": "risky",
          "fraud_ring_detected": "yes",
          "bot_detected": "yes"
        },
        "email": {
          "is_deliverable": "yes",
          "breach_count": 1,
          "first_breached_at": "1990-05-29",
          "last_breached_at": "1990-05-29",
          "domain_registered_at": "1990-05-29",
          "domain_is_free_provider": "yes",
          "domain_is_custom": "yes",
          "domain_is_disposable": "yes",
          "top_level_domain_is_suspicious": "yes",
          "linked_services": [
            "apple"
          ]
        },
        "phone": {
          "linked_services": [
            "apple"
          ]
        },
        "devices": [
          {
            "ip_proxy_type": "none_detected",
            "ip_spam_list_count": 1,
            "ip_timezone_offset": "+06:00:00"
          }
        ],
        "identity_abuse_signals": {
          "synthetic_identity": {
            "score": 0
          },
          "stolen_identity": {
            "score": 0
          }
        }
      },
      "verify_sms": {
        "status": "success",
        "verifications": [
          {
            "status": "success",
            "attempt": 1,
            "phone_number": "+12345678909",
            "delivery_attempt_count": 1,
            "solve_attempt_count": 1,
            "initially_sent_at": "2020-07-24T03:26:02Z",
            "last_sent_at": "2020-07-24T03:26:02Z",
            "redacted_at": "2020-07-24T03:26:02Z"
          }
        ]
      },
      "watchlist_screening_id": "scr_52xR9LKo77r1Np",
      "beacon_user_id": "becusr_42cF1MNo42r9Xj",
      "user_id": "usr_dddAs9ewdcDQQQ",
      "redacted_at": "2020-07-24T03:26:02Z"
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /identity\_verification/retry 

#### Retry an Identity Verification 

Allow a customer to retry their Identity Verification

#### Request fields 

**client\_user\_id** (required, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**template\_id** (required, string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**strategy** (required, string)  
An instruction specifying what steps the new Identity Verification attempt should require the user to complete: reset - Restart the user at the beginning of the session, regardless of whether they successfully completed part of their previous session. incomplete - Start the new session at the step that the user failed in the previous session, skipping steps that have already been successfully completed. infer - If the most recent Identity Verification attempt associated with the given client\_user\_id has a status of failed or expired, retry using the incomplete strategy. Otherwise, use the reset strategy. custom - Start the new session with a custom configuration, specified by the value of the steps field Note: The incomplete strategy cannot be applied if the session's failing step is screening or risk\_check. The infer strategy cannot be applied if the session's status is still active Possible values: reset, incomplete, infer, custom

**user** (object)  
User information collected outside of Link, most likely via your own onboarding process. Each of the following identity fields are optional: email\_address phone\_number date\_of\_birth name address id\_number Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the accept\_tos step, depending on the value provided to the gave\_consent field.

**user->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->phone\_number** (string)  
A valid phone number in E.164 format.

**user->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->name** (object)  
You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the identity verification attempt.

**user->name->given\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (required, string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (object)  
Home address for the user. Supported values are: not provided, address with only country code or full address. For more context on this field, see Input Validation by Country.

**user->address->street** (string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (required, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->id\_number** (object)  
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->id\_number->value** (required, string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (required, string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**steps** (object)  
Instructions for the custom retry strategy specifying which steps should be required or skipped. Note: This field must be provided when the retry strategy is custom and must be omitted otherwise. Custom retries override settings in your Plaid Template. For example, if your Plaid Template has verify\_sms disabled, a custom retry with verify\_sms enabled will still require the step. The selfie\_check step is currently not supported on the sandbox server. Sandbox requests will silently disable the selfie\_check step when provided.

**steps->verify\_sms** (required, boolean)  
A boolean field specifying whether the new session should require or skip the verify\_sms step.

**steps->kyc\_check** (required, boolean)  
A boolean field specifying whether the new session should require or skip the kyc\_check (Data Source Verification) step.

**steps->documentary\_verification** (required, boolean)  
A boolean field specifying whether the new session should require or skip the documentary\_verification step.

**steps->selfie\_check** (required, boolean)  
A boolean field specifying whether the new session should require or skip the selfie\_check step.

**is\_shareable** (boolean)  
A flag specifying whether you would like Plaid to expose a shareable URL for the verification being retried. If a value for this flag is not specified, the is\_shareable setting from the original verification attempt will be used.

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

```javascript
const request: IdentityVerificationRetryRequest = {
  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
  template_id: 'idvtmp_52xR9LKo77r1Np',
  strategy: 'reset',
  user: {
    email_address: 'acharleston@email.com',
    phone_number: '+12345678909',
    date_of_birth: '1975-01-18',
    name: {
      given_name: 'Anna',
      family_name: 'Charleston',
    },
    address: {
      street: '100 Market Street',
      street2: 'Apt 1A',
      city: 'San Francisco',
      region: 'CA',
      postal_code: '94103',
      country: 'US',
    },
    id_number: {
      value: '123456789',
      type: 'us_ssn',
    },
  },
};
try {
  const response = await plaidClient.identityVerificationRetry(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated Identity Verification attempt.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**completed\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**previous\_attempt\_id** (nullable, string)  
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.

**shareable\_url** (nullable, string)  
A shareable URL that can be sent directly to the user to complete verification

**template** (object)  
The resource ID and version number of the template configuring the behavior of a given Identity Verification.

**template->id** (string)  
ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive.

**template->version** (integer)  
Version of the associated Identity Verification template.

**user** (object)  
The identity data that was either collected from the user or provided via API in order to perform an Identity Verification.

**user->phone\_number** (nullable, string)  
A valid phone number in E.164 format.

**user->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**user->ip\_address** (nullable, string)  
An IPv4 or IPV6 address.

**user->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**user->name** (nullable, object)  
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**user->address** (nullable, object)  
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code

**user->address->street** (nullable, string)  
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.

**user->address->street2** (nullable, string)  
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.

**user->address->city** (nullable, string)  
City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."

**user->address->region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**user->address->postal\_code** (nullable, string)  
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**user->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**user->id\_number** (nullable, object)  
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

**user->id\_number->value** (string)  
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.

**user->id\_number->type** (string)  
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation. Possible values: ar\_dni, au\_drivers\_license, au\_passport, br\_cpf, ca\_sin, cl\_run, cn\_resident\_card, co\_nit, dk\_cpr, eg\_national\_id, es\_dni, es\_nie, hk\_hkid, in\_pan, it\_cf, jo\_civil\_id, jp\_my\_number, ke\_huduma\_namba, kw\_civil\_id, mx\_curp, mx\_rfc, my\_nric, ng\_nin, nz\_drivers\_license, om\_civil\_id, ph\_psn, pl\_pesel, ro\_cnp, sa\_national\_id, se\_pin, sg\_nric, tr\_tc\_kimlik, us\_ssn, us\_ssn\_last\_4, za\_smart\_id

**status** (string)  
The status of this Identity Verification attempt. active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template failed - The user failed one or more steps in the session and was told to contact support. expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: active, success, failed, expired, canceled, pending\_review

**steps** (object)  
Each step will be one of the following values: active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point. success - The Identity Verification attempt has completed this step. failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. waiting\_for\_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. not\_applicable - This step will not be run for this session. skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. expired - This step had not yet been completed when the Identity Verification attempt as a whole expired. canceled - The Identity Verification attempt was canceled before the user completed this step. pending\_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. manually\_approved - The step was manually overridden to pass by a team member in the dashboard. manually\_rejected - The step was manually overridden to fail by a team member in the dashboard.

**steps->accept\_tos** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->verify\_sms** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->kyc\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->documentary\_verification** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->selfie\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->watchlist\_screening** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**steps->risk\_check** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**documentary\_verification** (nullable, object)  
Data, images, analysis, and results from the documentary\_verification step. This field will be null unless steps.documentary\_verification has reached a terminal state of either success or failed.

**documentary\_verification->status** (string)  
The outcome status for the associated Identity Verification attempt's documentary\_verification step. This field will always have the same value as steps.documentary\_verification.

**documentary\_verification->documents** (\[object\])  
An array of documents submitted to the documentary\_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary\_verification is failed, the user has exhausted their retry attempts.

**documentary\_verification->documents->status** (string)  
An outcome status for this specific document submission. Distinct from the overall documentary\_verification.status that summarizes the verification outcome from one or more documents. Possible values: success, failed, manually\_approved

**documentary\_verification->documents->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent document upload.

**documentary\_verification->documents->images** (object)  
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.

**documentary\_verification->documents->images->original\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

**documentary\_verification->documents->images->original\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

**documentary\_verification->documents->images->cropped\_front** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

**documentary\_verification->documents->images->cropped\_back** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

**documentary\_verification->documents->images->face** (nullable, string)  
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

**documentary\_verification->documents->extracted\_data** (nullable, object)  
Data extracted from a user-submitted document.

**documentary\_verification->documents->extracted\_data->id\_number** (nullable, string)  
Alpha-numeric ID number extracted via OCR from the user's document image.

**documentary\_verification->documents->extracted\_data->category** (string)  
The type of identity document detected in the images provided. Will always be one of the following values: drivers\_license - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges id\_card - A general national identification card, distinct from driver's licenses as it only establishes identity passport - A travel passport issued by the associated country for one of its citizens residence\_permit\_card - An identity document issued by the associated country permitting a foreign citizen to temporarily reside there resident\_card - An identity document issued by the associated country permitting a foreign citizen to permanently reside there visa - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport Possible values: drivers\_license, id\_card, passport, residence\_permit\_card, resident\_card, visa

**documentary\_verification->documents->extracted\_data->expiration\_date** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**documentary\_verification->documents->extracted\_data->issuing\_country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**documentary\_verification->documents->extracted\_data->issuing\_region** (nullable, string)  
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**documentary\_verification->documents->extracted\_data->date\_of\_birth** (nullable, string)  
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**documentary\_verification->documents->extracted\_data->address** (nullable, object)  
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null. region, and postal\_code may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.

**documentary\_verification->documents->extracted\_data->address->street** (string)  
The full street address extracted from the document.

**documentary\_verification->documents->extracted\_data->address->city** (string)  
City extracted from the document.

**documentary\_verification->documents->extracted\_data->address->region** (nullable, string)  
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.

**documentary\_verification->documents->extracted\_data->address->postal\_code** (nullable, string)  
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

**documentary\_verification->documents->extracted\_data->address->country** (string)  
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

**documentary\_verification->documents->extracted\_data->name** (nullable, object)  
The individual's name extracted from the document.

**documentary\_verification->documents->extracted\_data->name->given\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**documentary\_verification->documents->extracted\_data->name->family\_name** (string)  
A string with at least one non-whitespace character, with a max length of 100 characters.

**documentary\_verification->documents->analysis** (object)  
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

**documentary\_verification->documents->analysis->authenticity** (string)  
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->image\_quality** (string)  
A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: high, medium, low

**documentary\_verification->documents->analysis->extracted\_data** (nullable, object)  
Analysis of the data extracted from the submitted document.

**documentary\_verification->documents->analysis->extracted\_data->name** (string)  
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->extracted\_data->date\_of\_birth** (string)  
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->extracted\_data->expiration\_date** (string)  
A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no\_data. Possible values: not\_expired, expired, no\_data

**documentary\_verification->documents->analysis->extracted\_data->issuing\_country** (string)  
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a no\_match on issuing\_country fails the documentary\_verification by editing your Plaid Template. Possible values: match, no\_match

**documentary\_verification->documents->analysis->aamva\_verification** (nullable, object)  
Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states.

**documentary\_verification->documents->analysis->aamva\_verification->is\_verified** (boolean)  
The overall outcome of checking the associated hit against the issuing state database.

**documentary\_verification->documents->analysis->aamva\_verification->id\_number** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->id\_issue\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->id\_expiration\_date** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->street** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->city** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->postal\_code** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->date\_of\_birth** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->gender** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->height** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->eye\_color** (string)  
The outcome of checking the particular field against state databases. match - The field is an exact match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->first\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->middle\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->analysis->aamva\_verification->last\_name** (string)  
The outcome of checking the associated hit against state databases. match - The field is an exact match with the state database. partial\_match - The field is a partial match with the state database. no\_match - The field is not an exact match with the state database. no\_data - The field was unable to be checked against state databases. Possible values: match, partial\_match, no\_match, no\_data

**documentary\_verification->documents->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**selfie\_check** (nullable, object)  
Additional information for the selfie\_check step. This field will be null unless steps.selfie\_check has reached a terminal state of either success or failed.

**selfie\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's selfie\_check step. This field will always have the same value as steps.selfie\_check. Possible values: success, failed

**selfie\_check->selfies** (\[object\])  
An array of selfies submitted to the selfie\_check step. Each entry represents one user submission.

**selfie\_check->selfies->status** (string)  
An outcome status for this specific selfie. Distinct from the overall selfie\_check.status that summarizes the verification outcome from one or more selfies. Possible values: success, failed

**selfie\_check->selfies->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent selfie upload.

**selfie\_check->selfies->capture** (object)  
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

**selfie\_check->selfies->capture->image\_url** (nullable, string)  
Temporary URL for downloading an image selfie capture.

**selfie\_check->selfies->capture->video\_url** (nullable, string)  
Temporary URL for downloading a video selfie capture.

**selfie\_check->selfies->analysis** (object)  
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

**selfie\_check->selfies->analysis->document\_comparison** (string)  
Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: match, no\_match, no\_input

**selfie\_check->selfies->analysis->liveness\_check** (string)  
Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: success, failed

**kyc\_check** (nullable, object)  
Additional information for the kyc\_check (Data Source Verification) step. This field will be null unless steps.kyc\_check has reached a terminal state of either success or failed.

**kyc\_check->status** (string)  
The outcome status for the associated Identity Verification attempt's kyc\_check step. This field will always have the same value as steps.kyc\_check.

**kyc\_check->address** (object)  
Result summary object specifying how the address field matched.

**kyc\_check->address->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->address->po\_box** (string)  
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no\_data when Plaid was not able to determine if the address is a P.O. box. Possible values: yes, no, no\_data

**kyc\_check->address->type** (string)  
Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be no\_data when Plaid does not have sufficient data to determine the address's use. Possible values: residential, commercial, no\_data

**kyc\_check->name** (object)  
Result summary object specifying how the name field matched.

**kyc\_check->name->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->date\_of\_birth** (object)  
Result summary object specifying how the date\_of\_birth field matched.

**kyc\_check->date\_of\_birth->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->id\_number** (object)  
Result summary object specifying how the id\_number field matched.

**kyc\_check->id\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->phone\_number** (object)  
Result summary object specifying how the phone field matched.

**kyc\_check->phone\_number->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**kyc\_check->phone\_number->area\_code** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**risk\_check** (nullable, object)  
Additional information for the risk\_check step.

**risk\_check->status** (string)  
The status of a step in the Identity Verification process. Possible values: success, active, failed, waiting\_for\_prerequisite, not\_applicable, skipped, expired, canceled, pending\_review, manually\_approved, manually\_rejected

**risk\_check->behavior** (nullable, object)  
Result summary object specifying values for behavior attributes of risk check, when available.

**risk\_check->behavior->user\_interactions** (string)  
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome. risky indicates the user has low familiarity with the data they are providing, and that fraud is likely. no\_data indicates there is not sufficient information to give an accurate signal. Possible values: genuine, neutral, risky, no\_data

**risk\_check->behavior->fraud\_ring\_detected** (string)  
Field describing the outcome of a fraud ring behavior risk check. yes indicates that fraud ring activity was detected. no indicates that fraud ring activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**risk\_check->behavior->bot\_detected** (string)  
Field describing the outcome of a bot detection behavior risk check. yes indicates that automated activity was detected. no indicates that automated activity was not detected. no\_data indicates there was not enough information available to give an accurate signal. Possible values: yes, no, no\_data

**risk\_check->email** (nullable, object)  
Result summary object specifying values for email attributes of risk check.

**risk\_check->email->is\_deliverable** (string)  
SMTP-MX check to confirm the email address exists if known. Possible values: yes, no, no\_data

**risk\_check->email->breach\_count** (nullable, integer)  
Count of all known breaches of this email address if known.

**risk\_check->email->first\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->last\_breached\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->domain\_registered\_at** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**risk\_check->email->domain\_is\_free\_provider** (string)  
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: yes, no, no\_data

**risk\_check->email->domain\_is\_custom** (string)  
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: yes, no, no\_data

**risk\_check->email->domain\_is\_disposable** (string)  
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: yes, no, no\_data

**risk\_check->email->top\_level\_domain\_is\_suspicious** (string)  
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: yes, no, no\_data

**risk\_check->email->linked\_services** (\[string\])  
A list of online services where this email address has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**risk\_check->phone** (nullable, object)  
Result summary object specifying values for phone attributes of risk check.

**risk\_check->phone->linked\_services** (\[string\])  
A list of online services where this phone number has been detected to have accounts or other activity. Possible values: aboutme, adobe, adult\_sites, airbnb, altbalaji, amazon, apple, archiveorg, atlassian, bitmoji, bodybuilding, booking, bukalapak, codecademy, deliveroo, diigo, discord, disneyplus, duolingo, ebay, envato, eventbrite, evernote, facebook, firefox, flickr, flipkart, foursquare, freelancer, gaana, giphy, github, google, gravatar, hubspot, imgur, instagram, jdid, kakao, kommo, komoot, lastfm, lazada, line, linkedin, mailru, microsoft, myspace, netflix, nike, ok, patreon, pinterest, plurk, quora, qzone, rambler, rappi, replit, samsung, seoclerks, shopclues, skype, snapchat, snapdeal, soundcloud, spotify, starz, strava, taringa, telegram, tiki, tokopedia, treehouse, tumblr, twitter, venmo, viber, vimeo, vivino, vkontakte, wattpad, weibo, whatsapp, wordpress, xing, yahoo, yandex, zalo, zoho

**risk\_check->devices** (\[object\])  
Array of result summary objects specifying values for device attributes of risk check.

**risk\_check->devices->ip\_proxy\_type** (nullable, string)  
An enum indicating whether a network proxy is present and if so what type it is. none\_detected indicates the user is not on a detectable proxy network. tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). vpn indicates the user is on a VPN (Virtual Private Network) web\_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. public\_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: none\_detected, tor, vpn, web\_proxy, public\_proxy

**risk\_check->devices->ip\_spam\_list\_count** (nullable, integer)  
Count of spam lists the IP address is associated with if known.

**risk\_check->devices->ip\_timezone\_offset** (nullable, string)  
UTC offset of the timezone associated with the IP address.

**risk\_check->identity\_abuse\_signals** (nullable, object)  
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected.

**risk\_check->identity\_abuse\_signals->synthetic\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**risk\_check->identity\_abuse\_signals->synthetic\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.

**risk\_check->identity\_abuse\_signals->stolen\_identity** (nullable, object)  
Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**risk\_check->identity\_abuse\_signals->stolen\_identity->score** (integer)  
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.

**verify\_sms** (nullable, object)  
Additional information for the verify\_sms step.

**verify\_sms->status** (string)  
The outcome status for the associated Identity Verification attempt's verify\_sms step. This field will always have the same value as steps.verify\_sms. Possible values: success, failed

**verify\_sms->verifications** (\[object\])  
An array where each entry represents a verification attempt for the verify\_sms step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications.

**verify\_sms->verifications->status** (string)  
The outcome status for the individual SMS verification. Possible values: pending, success, failed, canceled

**verify\_sms->verifications->attempt** (integer)  
The attempt field begins with 1 and increments with each subsequent SMS verification.

**verify\_sms->verifications->phone\_number** (nullable, string)  
A phone number in E.164 format.

**verify\_sms->verifications->delivery\_attempt\_count** (integer)  
The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification.

**verify\_sms->verifications->solve\_attempt\_count** (integer)  
The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification.

**verify\_sms->verifications->initially\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**verify\_sms->verifications->last\_sent\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**verify\_sms->verifications->redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_screening\_id** (nullable, string)  
ID of the associated screening.

**beacon\_user\_id** (nullable, string)  
ID of the associated Beacon User.

**user\_id** (nullable, string)  
A unique user\_id generated by Plaid for the client-provided client\_user\_id. This field is currently in beta.

**redacted\_at** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "idv_52xR9LKo77r1Np",
  "client_user_id": "your-db-id-3b24110",
  "created_at": "2020-07-24T03:26:02Z",
  "completed_at": "2020-07-24T03:26:02Z",
  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
  "template": {
    "id": "idvtmp_4FrXJvfQU3zGUR",
    "version": 2
  },
  "user": {
    "phone_number": "+12345678909",
    "date_of_birth": "1990-05-29",
    "ip_address": "192.0.2.42",
    "email_address": "user@example.com",
    "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"
    }
  },
  "status": "success",
  "steps": {
    "accept_tos": "success",
    "verify_sms": "success",
    "kyc_check": "success",
    "documentary_verification": "success",
    "selfie_check": "success",
    "watchlist_screening": "success",
    "risk_check": "success"
  },
  "documentary_verification": {
    "status": "success",
    "documents": [
      {
        "status": "success",
        "attempt": 1,
        "images": {
          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
        },
        "extracted_data": {
          "id_number": "AB123456",
          "category": "drivers_license",
          "expiration_date": "1990-05-29",
          "issuing_country": "US",
          "issuing_region": "IN",
          "date_of_birth": "1990-05-29",
          "address": {
            "street": "123 Main St. Unit 42",
            "city": "Pawnee",
            "region": "IN",
            "postal_code": "46001",
            "country": "US"
          },
          "name": {
            "given_name": "Leslie",
            "family_name": "Knope"
          }
        },
        "analysis": {
          "authenticity": "match",
          "image_quality": "high",
          "extracted_data": {
            "name": "match",
            "date_of_birth": "match",
            "expiration_date": "not_expired",
            "issuing_country": "match"
          },
          "aamva_verification": {
            "is_verified": true,
            "id_number": "match",
            "id_issue_date": "match",
            "id_expiration_date": "match",
            "street": "match",
            "city": "match",
            "postal_code": "match",
            "date_of_birth": "match",
            "gender": "match",
            "height": "match",
            "eye_color": "match",
            "first_name": "match",
            "middle_name": "match",
            "last_name": "match"
          }
        },
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "selfie_check": {
    "status": "success",
    "selfies": [
      {
        "status": "success",
        "attempt": 1,
        "capture": {
          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
        },
        "analysis": {
          "document_comparison": "match",
          "liveness_check": "success"
        }
      }
    ]
  },
  "kyc_check": {
    "status": "success",
    "address": {
      "summary": "match",
      "po_box": "yes",
      "type": "residential"
    },
    "name": {
      "summary": "match"
    },
    "date_of_birth": {
      "summary": "match"
    },
    "id_number": {
      "summary": "match"
    },
    "phone_number": {
      "summary": "match",
      "area_code": "match"
    }
  },
  "risk_check": {
    "status": "success",
    "behavior": {
      "user_interactions": "risky",
      "fraud_ring_detected": "yes",
      "bot_detected": "yes"
    },
    "email": {
      "is_deliverable": "yes",
      "breach_count": 1,
      "first_breached_at": "1990-05-29",
      "last_breached_at": "1990-05-29",
      "domain_registered_at": "1990-05-29",
      "domain_is_free_provider": "yes",
      "domain_is_custom": "yes",
      "domain_is_disposable": "yes",
      "top_level_domain_is_suspicious": "yes",
      "linked_services": [
        "apple"
      ]
    },
    "phone": {
      "linked_services": [
        "apple"
      ]
    },
    "devices": [
      {
        "ip_proxy_type": "none_detected",
        "ip_spam_list_count": 1,
        "ip_timezone_offset": "+06:00:00"
      }
    ],
    "identity_abuse_signals": {
      "synthetic_identity": {
        "score": 0
      },
      "stolen_identity": {
        "score": 0
      }
    }
  },
  "verify_sms": {
    "status": "success",
    "verifications": [
      {
        "status": "success",
        "attempt": 1,
        "phone_number": "+12345678909",
        "delivery_attempt_count": 1,
        "solve_attempt_count": 1,
        "initially_sent_at": "2020-07-24T03:26:02Z",
        "last_sent_at": "2020-07-24T03:26:02Z",
        "redacted_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "user_id": "usr_dddAs9ewdcDQQQ",
  "redacted_at": "2020-07-24T03:26:02Z",
  "request_id": "saKrIBuEB9qJZng"
}
```

### Webhooks 

\=\*=\*=\*=

#### STATUS\_UPDATED 

Fired when the status of an identity verification has been updated, which can be triggered via the dashboard or the API.

#### Properties 

**webhook\_type** (string)  
IDENTITY\_VERIFICATION

**webhook\_code** (string)  
STATUS\_UPDATED

**identity\_verification\_id** (string)  
The ID of the associated Identity Verification attempt.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "IDENTITY_VERIFICATION",
  "webhook_code": "STATUS_UPDATED",
  "identity_verification_id": "idv_52xR9LKo77r1Np",
  "environment": "production"
}
```

\=\*=\*=\*=

#### STEP\_UPDATED 

Fired when an end user has completed a step of the Identity Verification process.

#### Properties 

**webhook\_type** (string)  
IDENTITY\_VERIFICATION

**webhook\_code** (string)  
STEP\_UPDATED

**identity\_verification\_id** (string)  
The ID of the associated Identity Verification attempt.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "IDENTITY_VERIFICATION",
  "webhook_code": "STEP_UPDATED",
  "identity_verification_id": "idv_52xR9LKo77r1Np",
  "environment": "production"
}
```

\=\*=\*=\*=

#### RETRIED 

Fired when identity verification has been retried, which can be triggered via the dashboard or the API.

#### Properties 

**webhook\_type** (string)  
IDENTITY\_VERIFICATION

**webhook\_code** (string)  
RETRIED

**identity\_verification\_id** (string)  
The ID of the associated Identity Verification attempt.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "IDENTITY_VERIFICATION",
  "webhook_code": "RETRIED",
  "identity_verification_id": "idv_52xR9LKo77r1Np",
  "environment": "production"
}
```

---


# API - Identity | Plaid Docs

Identity 
=========

#### API reference for Identity endpoints and webhooks 

Verify the name, address, phone number, and email address of a user against bank account information on file. For how-to guidance, see the [Identity documentation](https://plaid.com/docs/identity/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) | Fetch identity data |
| [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) | Match client identity with bank identity |
| [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) | Get Identity data parsed from an uploaded bank statement |

### Endpoints 

\=\*=\*=\*=

#### /identity/get 

#### Retrieve identity data 

The [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses. Only name data is guaranteed to be returned; other fields will be empty arrays if not provided by the institution.  
Note: In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /identity/get results.

**options->account\_ids** (\[string\])  
A list of account\_ids to retrieve for the Item. Note: An error will be returned if a provided account\_id is not associated with the Item.

```javascript
// Pull Identity data for an Item
const request: IdentityGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.identityGet(request);
  const identities = response.data.accounts.flatMap(
    (account) => account.owners,
  );
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
The accounts for which Identity data has been requested

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution; detecting whether the linked account is a business account is not currently supported. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning

**accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**accounts->owners->phone\_numbers->data** (string)  
The phone number.

**accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**accounts->owners->emails->data** (string)  
The email address.

**accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "owners": [
        {
          "addresses": [
            {
              "data": {
                "city": "Malakoff",
                "country": "US",
                "postal_code": "14236",
                "region": "NY",
                "street": "2992 Cameron Road"
              },
              "primary": true
            },
            {
              "data": {
                "city": "San Matias",
                "country": "US",
                "postal_code": "93405-2255",
                "region": "CA",
                "street": "2493 Leisure Lane"
              },
              "primary": false
            }
          ],
          "emails": [
            {
              "data": "accountholder0@example.com",
              "primary": true,
              "type": "primary"
            },
            {
              "data": "accountholder1@example.com",
              "primary": false,
              "type": "secondary"
            },
            {
              "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
              "primary": false,
              "type": "other"
            }
          ],
          "names": [
            "Alberta Bobbeth Charleson"
          ],
          "phone_numbers": [
            {
              "data": "2025550123",
              "primary": false,
              "type": "home"
            },
            {
              "data": "1112224444",
              "primary": false,
              "type": "work"
            },
            {
              "data": "1112225555",
              "primary": false,
              "type": "mobile"
            }
          ]
        }
      ],
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "balances": {
        "available": 200,
        "current": 210,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "1111",
      "name": "Plaid Saving",
      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
      "owners": [
        {
          "addresses": [
            {
              "data": {
                "city": "Malakoff",
                "country": "US",
                "postal_code": "14236",
                "region": "NY",
                "street": "2992 Cameron Road"
              },
              "primary": true
            },
            {
              "data": {
                "city": "San Matias",
                "country": "US",
                "postal_code": "93405-2255",
                "region": "CA",
                "street": "2493 Leisure Lane"
              },
              "primary": false
            }
          ],
          "emails": [
            {
              "data": "accountholder0@example.com",
              "primary": true,
              "type": "primary"
            },
            {
              "data": "accountholder1@example.com",
              "primary": false,
              "type": "secondary"
            },
            {
              "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
              "primary": false,
              "type": "other"
            }
          ],
          "names": [
            "Alberta Bobbeth Charleson"
          ],
          "phone_numbers": [
            {
              "data": "2025550123",
              "primary": false,
              "type": "home"
            },
            {
              "data": "1112224444",
              "primary": false,
              "type": "work"
            },
            {
              "data": "1112225555",
              "primary": false,
              "type": "mobile"
            }
          ]
        }
      ],
      "subtype": "savings",
      "type": "depository"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "identity",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "institution_name": "Chase",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "3nARps6TOYtbACO"
}
```

\=\*=\*=\*=

#### /identity/match 

#### Retrieve identity match score 

The [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution.  
Fields within the `balances` object will always be null when retrieved by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . Instead, use the free [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint to request balance cached data, or [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) for real-time data.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**user** (object)  
The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks.

**user->legal\_name** (string)  
The user's full legal name.

**user->phone\_number** (string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
Data about the components comprising an address.

**user->address->city** (string)  
The full city name

**user->address->region** (string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**user->address->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**user->address->postal\_code** (string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**user->address->country** (string)  
The ISO 3166-1 alpha-2 country code

**options** (object)  
An optional object to filter /identity/match results

**options->account\_ids** (\[string\])  
An array of account\_ids to perform fuzzy match

```javascript
const request = {
  access_token: accessToken,
  // Omit user object if using Identity Verification Financial Account Matching
  user: {
    legal_name: 'Jane Smith',
    phone_number: '+14155552671',
    email_address: 'jane.smith@example.com',
    address: {
      street: '500 Market St',
      city: 'San Francisco',
      region: 'CA',
      postal_code: '94105',
      country: 'US',
    },
  },
};


try {
  const response = await plaidClient.identityMatch(request);
  const accounts = response.data.accounts;
  for (const account of accounts) {
    const legalNameScore = account.legal_name?.score;
    const phoneScore = account.phone_number?.score;
    const emailScore = account.email_address?.score;
    const addressScore = account.address?.score;
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
The accounts for which Identity match has been requested

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**accounts->legal\_name** (nullable, object)  
Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled.

**accounts->legal\_name->score** (nullable, integer)  
Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null.

**accounts->legal\_name->is\_first\_name\_or\_last\_name\_match** (nullable, boolean)  
first or last name completely matched, likely a family member

**accounts->legal\_name->is\_nickname\_match** (nullable, boolean)  
nickname matched, example Jennifer and Jenn.

**accounts->legal\_name->is\_business\_name\_detected** (nullable, boolean)  
Is true if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A true result generally indicates that an account's name is a business name. However, a false result does not mean the account name is not a business name, as some businesses do not use these strings in the names used for their financial institution accounts.

**accounts->phone\_number** (nullable, object)  
Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.

**accounts->phone\_number->score** (nullable, integer)  
Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension, etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null.

**accounts->email\_address** (nullable, object)  
Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.

**accounts->email\_address->score** (nullable, integer)  
Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null.

**accounts->address** (nullable, object)  
Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.

**accounts->address->score** (nullable, integer)  
Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-70 is a partial match, anything below 70 is considered a weak match. Typically, the match threshold should be set to a score of 70 or higher. If the address is missing from either the API or financial institution, this is null.

**accounts->address->is\_postal\_code\_match** (nullable, boolean)  
postal code was provided for both and was a match

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": null,
        "current": null,
        "iso_currency_code": null,
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "legal_name": {
        "score": 90,
        "is_nickname_match": true,
        "is_first_name_or_last_name_match": true,
        "is_business_name_detected": false
      },
      "phone_number": {
        "score": 100
      },
      "email_address": {
        "score": 100
      },
      "address": {
        "score": 100,
        "is_postal_code_match": true
      },
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "balances": {
        "available": null,
        "current": null,
        "iso_currency_code": null,
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "1111",
      "name": "Plaid Saving",
      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
      "legal_name": {
        "score": 30,
        "is_first_name_or_last_name_match": false
      },
      "phone_number": {
        "score": 100
      },
      "email_address": null,
      "address": {
        "score": 100,
        "is_postal_code_match": true
      },
      "subtype": "savings",
      "type": "depository"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "identity",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "institution_name": "Chase",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "3nARps6TOYtbACO"
}
```

\=\*=\*=\*=

#### /identity/documents/uploads/get 

#### Returns uploaded document identity 

Use [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) to retrieve identity details when using [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /identity/documents/uploads/get results.

**options->account\_ids** (\[string\])  
A list of account\_ids to retrieve for the Item. Note: An error will be returned if a provided account\_id is not associated with the Item.

```javascript
const request: IdentityDocumentsUploadsGetRequest = {
  access_token: accessToken,
};
try {
  const response = await client.identityDocumentsUploadsGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
The accounts for which Identity data has been requested

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution; detecting whether the linked account is a business account is not currently supported. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning

**accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**accounts->owners->phone\_numbers->data** (string)  
The phone number.

**accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**accounts->owners->emails->data** (string)  
The email address.

**accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**accounts->documents** (nullable, \[object\])  
Data about the documents that were uploaded as proof of account ownership.

**accounts->documents->document\_id** (string)  
A UUID identifying the document.

**accounts->documents->metadata** (object)  
Metadata pertaining to the document.

**accounts->documents->metadata->document\_type** (nullable, string)  
The submitted document type. Currently, this will always be BANK\_STATEMENT.

**accounts->documents->metadata->is\_account\_number\_match** (nullable, boolean)  
Boolean field indicating whether the uploaded document's account number matches the account number we have on file. If false, it is not recommended to accept the uploaded identity data as accurate without further verification.

**accounts->documents->metadata->page\_count** (nullable, integer)  
The number of pages in the uploaded document.

**accounts->documents->metadata->last\_updated** (string)  
The timestamp when the document was last updated. Format: date-time

**accounts->documents->metadata->uploaded\_at** (string)  
The timestamp when the document was originally uploaded. Format: date-time

**accounts->documents->risk\_insights** (object)  
Object representing fraud risk data of the uploaded document. Only provided when using Identity Document Upload with Fraud Risk enabled.

**accounts->documents->risk\_insights->risk\_summary** (object)  
Risk summary of an uploaded document.

**accounts->documents->risk\_insights->risk\_summary->risk\_score** (nullable, integer)  
A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent.

**accounts->documents->risk\_insights->risk\_signals** (\[object\])  
An array of risk signals.

**accounts->documents->risk\_insights->risk\_signals->type** (nullable, string)  
The type of risk found. Possible values: FONT, MASKING, OVERLAID\_TEXT, EDITED\_TEXT, TEXT\_COMPRESSION, ADDRESS\_FORMAT\_ANOMALY, DATE\_FORMAT\_ANOMALY, FONT\_ANOMALY, NAME\_FORMAT\_ANOMALY, PDF\_ALIGNMENT, BRUSH\_DETECTION, METADATA\_DATES\_OUTSIDE\_WINDOW, METADATA\_DATES\_INSIDE\_WINDOW, METADATA\_DATES\_MISSING, METADATA\_DATES\_MATCH, ADOBE\_FONTS, ANNOTATION\_DATES, ANNOTATIONS, EDITED\_WHILE\_SCANNED, EXIF\_DATA\_MODIFIED, HIGH\_USER\_ACCESS, MALFORMED\_DATE, QPDF, TEXT\_LAYER\_TEXT, TOUCHUP\_TEXT, FLATTENED\_PDF, BLACKLISTS, COPYCAT\_IMAGE, COPYCAT\_TEXT, REJECTED\_CUSTOMER, TEMPLATES, SOFTWARE\_BLACKLIST

**accounts->documents->risk\_insights->risk\_signals->has\_fraud\_risk** (nullable, boolean)  
Indicates whether fraud risk was detected on the field.

**accounts->documents->risk\_insights->risk\_signals->signal\_description** (nullable, string)  
A human-readable explanation providing more detail about the specific risk signal.

**accounts->documents->risk\_insights->risk\_signals->page\_number** (nullable, integer)  
The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0.

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "ZXEbW7Rkr9iv1qj8abebU1KDMlkexgSgrLAod",
      "balances": {
        "available": null,
        "current": null,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "documents": [
        {
          "document_id": "9f838fef-b0a5-4ef4-bf73-8e5248d43ad7",
          "metadata": {
            "document_type": "BANK_STATEMENT",
            "is_account_number_match": true,
            "last_updated": "2024-09-25T23:57:12Z",
            "page_count": 1,
            "uploaded_at": "2024-09-25T23:57:12Z"
          },
          "risk_insights": {
            "risk_signals": [
              {
                "has_fraud_risk": true,
                "page_number": 0,
                "signal_description": "Creation date and modification date do not match",
                "type": "METADATA_DATES_OUTSIDE_WINDOW"
              },
              {
                "has_fraud_risk": true,
                "page_number": 0,
                "signal_description": "Adobe Acrobat",
                "type": "SOFTWARE_BLACKLIST"
              }
            ],
            "risk_summary": {
              "risk_score": 100
            }
          }
        }
      ],
      "mask": "0000",
      "name": "Checking ...0000",
      "official_name": null,
      "owners": [
        {
          "addresses": [
            {
              "data": {
                "city": "OAKLAND",
                "country": "US",
                "postal_code": "94103",
                "region": "CA",
                "street": "1234 GRAND AVE"
              },
              "primary": true
            }
          ],
          "document_id": "9f838fef-b0a5-4ef4-bf73-8e5248d43ad7",
          "emails": [],
          "names": [
            "JANE DOE"
          ],
          "phone_numbers": []
        }
      ],
      "subtype": "checking",
      "type": "depository",
      "verification_status": "manually_verified"
    }
  ],
  "item": {
    "available_products": [],
    "billed_products": [
      "auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "item_id": "QwpzDByRv8uvdpwKEW3WU4PkGEApajtp3o4NN",
    "products": [
      "auth"
    ],
    "update_type": "background",
    "webhook": "https://www.example.com/webhook"
  },
  "request_id": "b5jvmskusjwX5Gs"
}
```

### Webhooks (beta) 

This feature is in currently in beta; please reach out to your Plaid Account Manager if you would like it enabled.

\=\*=\*=\*=

#### DEFAULT\_UPDATE 

Fired when a change to identity data has been detected on an Item. Items are checked for identity updates every 30-90 days. We recommend that upon receiving this webhook you make another call to [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) to fetch the user's latest identity data.

#### Properties 

**webhook\_type** (string)  
IDENTITY

**webhook\_code** (string)  
DEFAULT\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**account\_ids\_with\_updated\_identity** (object)  
An object with keys of account\_id's that are mapped to their respective identity attributes that changed. Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": \["PHONES"\] }

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "IDENTITY",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "account_ids_with_updated_identity": {
    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp": [
      "ADDRESSES"
    ]
  },
  "error": null,
  "environment": "production"
}
```

---


# API - Income | Plaid Docs

Income 
=======

#### API reference for Income endpoints and webhooks 

Verify a user's income via payroll or bank account data. For how-to guidance, see the [Income documentation](https://plaid.com/docs/income/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) | Get Link session metadata and results for the end user |
| [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) | Retrieve information from the bank accounts used for income verification |
| [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) | Retrieve information from the bank accounts used for income verification in PDF format |
| [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) | Refresh a user's bank income information |
| [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) | Retrieve information from the bank statements used for income verification |
| [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) | Retrieve information from the pay stubs or tax forms used for income verification |
| [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) | Analyze uploaded income documents for indications of potential fraud |
| [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) | Update the parsing configuration for a document verification |
| [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) | (Beta) Retrieve employment information about the end user |
| [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) | (Beta) Retrieve updated payroll income data on a linked account |

| See also |  |
| --- | --- |
| [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) | Manually fire an Income webhook (Sandbox only) |
| [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | Create a user for use with the income verification product |

| Webhooks |  |
| --- | --- |
| [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) | Income verification has completed |
| [INCOME\_VERIFICATION\_RISK\_SIGNALS](https://plaid.com/docs/api/products/income/index.html.md#income_verification_risk_signals) | Risk evaluation of user-uploaded documents has completed |
| [BANK\_INCOME\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/income/index.html.md#bank_income_refresh_complete) | The refreshed report has finished generating |
| [INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED](https://plaid.com/docs/api/products/income/index.html.md#income_verification_refresh_reconnect_needed) | A Payroll Income verification could not be refreshed |

### Endpoints 

\=\*=\*=\*=

#### /user/create 

#### Create user 

This endpoint should be called for each of your end users before they begin a Plaid Check or Income flow, or a Multi-Item Link flow. This provides you a single token to access all data associated with the user. You should only create one per end user.  
The `consumer_report_user_identity` object must be present in order to create a Plaid Check Consumer Report for a user. If it is not provided during the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) call, it can be added later by calling [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) . Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`.  
If you call the endpoint multiple times with the same `client_user_id`, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given `client_user_id`.  
Ensure that you store the `user_token` along with your user's identifier in your database, as it is not possible to retrieve a previously created `user_token`.

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

**client\_user\_id** (required, string)  
A unique ID representing the end user. Maximum of 128 characters. 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. Max length: 128 Min length: 1

**consumer\_report\_user\_identity** (object)  
To create a Plaid Check Consumer Report for a user, this field must be present on the user token. If this field is not provided during user token creation, you can add it to the user later by calling /user/update. Once the field has been added to the user, you will be able to call /link/token/create with a non-empty consumer\_report\_permissible\_purpose (which will automatically create a Plaid Check Consumer Report), or call /cra/check\_report/create for that user.

**consumer\_report\_user\_identity->first\_name** (required, string)  
The user's first name

**consumer\_report\_user\_identity->last\_name** (required, string)  
The user's last name

**consumer\_report\_user\_identity->phone\_numbers** (required, \[string\])  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**consumer\_report\_user\_identity->emails** (required, \[string\])  
The user's emails

**consumer\_report\_user\_identity->ssn\_last\_4** (string)  
The last 4 digits of the user's social security number. Max length: 4 Min length: 4

**consumer\_report\_user\_identity->date\_of\_birth** (required, string)  
To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers. Format: date

**consumer\_report\_user\_identity->primary\_address** (required, object)  
Data about the components comprising an address.

**consumer\_report\_user\_identity->primary\_address->city** (required, string)  
The full city name

**consumer\_report\_user\_identity->primary\_address->region** (required, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**consumer\_report\_user\_identity->primary\_address->street** (required, string)  
The full street address Example: "564 Main Street, APT 15"

**consumer\_report\_user\_identity->primary\_address->postal\_code** (required, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**consumer\_report\_user\_identity->primary\_address->country** (required, string)  
The ISO 3166-1 alpha-2 country code

```javascript
const request: UserCreateRequest = {
  client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d',
};


try {
  const response = await client.userCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**user\_token** (string)  
The user token associated with the User data is being requested for.

**user\_id** (string)  
The Plaid user\_id of the User associated with this webhook, warning, or error.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /credit/sessions/get 

#### Retrieve Link sessions for your user 

This endpoint can be used for your end users after they complete the Link flow. This endpoint returns a list of Link sessions that your user completed, where each session includes the results from the Link flow.  
These results include details about the Item that was created and some product related metadata (showing, for example, whether the user finished the bank income verification step).

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

```javascript
const request: CreditSessionsGetRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
};


try {
  const response = await client.creditSessionsGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**sessions** (\[object\])  
A list of Link sessions for the user. Sessions will be sorted in reverse chronological order.

**sessions->link\_session\_id** (string)  
The unique identifier associated with the Link session. This identifier matches the link\_session\_id returned in the onSuccess/onExit callbacks.

**sessions->session\_start\_time** (string)  
The time when the Link session started Format: date-time

**sessions->results** (object)  
The set of results for a Link session.

**sessions->results->item\_add\_results** (\[object\])  
The set of Item adds for the Link session.

**sessions->results->item\_add\_results->public\_token** (string)  
Returned once a user has successfully linked their Item.

**sessions->results->item\_add\_results->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.

**sessions->results->item\_add\_results->institution\_id** (string)  
The Plaid Institution ID associated with the Item.

**sessions->results->bank\_income\_results** (\[object\])  
The set of bank income verifications for the Link session.

**sessions->results->bank\_income\_results->status** (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. Possible values: APPROVED, NO\_DEPOSITS\_FOUND, USER\_REPORTED\_NO\_INCOME

**sessions->results->bank\_income\_results->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.

**sessions->results->bank\_income\_results->institution\_id** (string)  
The Plaid Institution ID associated with the Item.

**sessions->results->bank\_employment\_results** (\[object\])  
The set of bank employment verifications for the Link session.

**sessions->results->bank\_employment\_results->status** (string)  
Status of the Bank Employment Link session. APPROVED: User has approved and verified their employment. NO\_EMPLOYMENTS\_FOUND: We attempted, but were unable to find any employment in the connected account. EMPLOYER\_NOT\_LISTED: The user explicitly indicated that they did not see their current or previous employer in the list of employer names found. STARTED: The user began the bank income portion of the link flow. INTERNAL\_ERROR: The user encountered an internal error. Possible values: APPROVED, NO\_EMPLOYERS\_FOUND, EMPLOYER\_NOT\_LISTED

**sessions->results->bank\_employment\_results->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.

**sessions->results->bank\_employment\_results->institution\_id** (string)  
The Plaid Institution ID associated with the Item.

**sessions->results->payroll\_income\_results** (\[object\])  
The set of payroll income verifications for the Link session.

**sessions->results->payroll\_income\_results->num\_paystubs\_retrieved** (integer)  
The number of paystubs retrieved from a payroll provider.

**sessions->results->payroll\_income\_results->num\_w2s\_retrieved** (integer)  
The number of w2s retrieved from a payroll provider.

**sessions->results->payroll\_income\_results->institution\_id** (string)  
The Plaid Institution ID associated with the Item.

**sessions->results->payroll\_income\_results->institution\_name** (string)  
The Institution Name associated with the Item.

**sessions->results->document\_income\_results** (nullable, object)  
The details of a document income verification in Link

**sessions->results->document\_income\_results->num\_paystubs\_uploaded** (integer)  
The number of paystubs uploaded by the user.

**sessions->results->document\_income\_results->num\_w2s\_uploaded** (integer)  
The number of w2s uploaded by the user.

**sessions->results->document\_income\_results->num\_bank\_statements\_uploaded** (integer)  
The number of bank statements uploaded by the user.

**sessions->results->document\_income\_results->num\_1099s\_uploaded** (integer)  
The number of 1099s uploaded by the user

**sessions->errors** (\[object\])  
The set of errors that occurred during the Link session.

**sessions->errors->error\_type** (string)  
A broad categorization of the error.

**sessions->errors->error\_code** (string)  
The particular error code.

**sessions->errors->error\_message** (string)  
A developer-friendly representation of the error code.

**sessions->errors->display\_message** (nullable, string)  
A user-friendly representation of the error code. null if the error is not related to user action.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "request_id": "Aim3b",
  "sessions": [
    {
      "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
      "results": {
        "item_add_results": [
          {
            "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",
            "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
            "institution_id": "ins_56"
          }
        ],
        "bank_income_results": [
          {
            "status": "APPROVED",
            "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
            "institution_id": "ins_56"
          }
        ]
      },
      "session_start_time": "2022-09-30T23:40:30.946225Z"
    },
    {
      "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9",
      "results": {
        "payroll_income_results": [
          {
            "num_paystubs_retrieved": 2,
            "num_w2s_retrieved": 1,
            "institution_id": "ins_92"
          }
        ]
      },
      "session_start_time": "2022-09-26T23:40:30.946225Z"
    }
  ]
}
```

\=\*=\*=\*=

#### /credit/bank\_income/get 

#### Retrieve information from the bank accounts used for income verification 

[/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) returns the bank income report(s) for a specified user. A single report corresponds to all institutions linked in a single Link session. To include multiple institutions in a single report, use [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . To return older reports, use the `options.count` field.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

**options** (object)  
An optional object for /credit/bank\_income/get request options.

**options->count** (integer)  
How many Bank Income Reports should be fetched. Multiple reports may be available if the report has been re-created or refreshed. If more than one report is available, the most recent reports will be returned first. Default: 1

```javascript
const request: CreditBankIncomeGetRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
  options: {
    count: 1,
  },
};


try {
  const response = await client.creditBankIncomeGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**bank\_income** (\[object\])  
The unique identifier associated with the Bank Income Report.

**bank\_income->generated\_time** (string)  
The time when the report was generated. Format: date-time

**bank\_income->days\_requested** (integer)  
The number of days requested by the customer for the report.

**bank\_income->items** (\[object\])  
The list of Items in the report along with the associated metadata about the Item.

**bank\_income->items->bank\_income\_accounts** (\[object\])  
The Item's accounts that have Bank Income data.

**bank\_income->items->bank\_income\_accounts->account\_id** (string)  
Plaid's unique identifier for the account.

**bank\_income->items->bank\_income\_accounts->mask** (nullable, 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, and it may also not match the mask that the bank displays to the user.

**bank\_income->items->bank\_income\_accounts->name** (string)  
The name of the bank account.

**bank\_income->items->bank\_income\_accounts->official\_name** (nullable, string)  
The official name of the bank account.

**bank\_income->items->bank\_income\_accounts->subtype** (string)  
Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas. Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all

**bank\_income->items->bank\_income\_accounts->type** (string)  
The account type. This will always be depository. Possible values: depository

**bank\_income->items->bank\_income\_accounts->owners** (\[object\])  
Data returned by the financial institution about the account owner or owners. Identity information is optional, so field may return an empty array.

**bank\_income->items->bank\_income\_accounts->owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**bank\_income->items->bank\_income\_accounts->owners->phone\_numbers** (\[object\])  
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**bank\_income->items->bank\_income\_accounts->owners->phone\_numbers->data** (string)  
The phone number.

**bank\_income->items->bank\_income\_accounts->owners->phone\_numbers->primary** (boolean)  
When true, identifies the phone number as the primary number on an account.

**bank\_income->items->bank\_income\_accounts->owners->phone\_numbers->type** (string)  
The type of phone number. Possible values: home, work, office, mobile, mobile1, other

**bank\_income->items->bank\_income\_accounts->owners->emails** (\[object\])  
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**bank\_income->items->bank\_income\_accounts->owners->emails->data** (string)  
The email address.

**bank\_income->items->bank\_income\_accounts->owners->emails->primary** (boolean)  
When true, identifies the email address as the primary email on an account.

**bank\_income->items->bank\_income\_accounts->owners->emails->type** (string)  
The type of email account as described by the financial institution. Possible values: primary, secondary, other

**bank\_income->items->bank\_income\_accounts->owners->addresses** (\[object\])  
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.

**bank\_income->items->bank\_income\_accounts->owners->addresses->data** (object)  
Data about the components comprising an address.

**bank\_income->items->bank\_income\_accounts->owners->addresses->data->city** (nullable, string)  
The full city name

**bank\_income->items->bank\_income\_accounts->owners->addresses->data->region** (nullable, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**bank\_income->items->bank\_income\_accounts->owners->addresses->data->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**bank\_income->items->bank\_income\_accounts->owners->addresses->data->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**bank\_income->items->bank\_income\_accounts->owners->addresses->data->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**bank\_income->items->bank\_income\_accounts->owners->addresses->primary** (boolean)  
When true, identifies the address as the primary address on an account.

**bank\_income->items->bank\_income\_sources** (\[object\])  
The income sources for this Item. Each entry in the array is a single income source.

**bank\_income->items->bank\_income\_sources->income\_source\_id** (string)  
A unique identifier for an income source.

**bank\_income->items->bank\_income\_sources->income\_description** (string)  
The most common name or original description for the underlying income transactions.

**bank\_income->items->bank\_income\_sources->income\_category** (string)  
The income category. BANK\_INTEREST: Interest earned from a bank account. BENEFIT\_OTHER: Government benefits other than retirement, unemployment, child support, or disability. Currently used only in the UK, to represent benefits such as Cost of Living Payments. CASH: Deprecated and used only for existing legacy implementations. Has been replaced by CASH\_DEPOSIT and TRANSFER\_FROM\_APPLICATION. CASH\_DEPOSIT: A cash or check deposit. CHILD\_SUPPORT: Child support payments received. GIG\_ECONOMY: Income earned as a gig economy worker, e.g. driving for Uber, Lyft, Postmates, DoorDash, etc. LONG\_TERM\_DISABILITY: Disability payments, including Social Security disability benefits. OTHER: Income that could not be categorized as any other income category. MILITARY: Veterans benefits. Income earned as salary for serving in the military (e.g. through DFAS) will be classified as SALARY rather than MILITARY. RENTAL: Income earned from a rental property. Income may be identified as rental when the payment is received through a rental platform, e.g. Airbnb; rent paid directly by the tenant to the property owner (e.g. via cash, check, or ACH) will typically not be classified as rental income. RETIREMENT: Payments from private retirement systems, pensions, and government retirement programs, including Social Security retirement benefits. SALARY: Payment from an employer to an earner or other form of permanent employment. TAX\_REFUND: A tax refund. TRANSFER\_FROM\_APPLICATION: Deposits from a money transfer app, such as Venmo, Cash App, or Zelle. UNEMPLOYMENT: Unemployment benefits. In the UK, includes certain low-income benefits such as the Universal Credit. Possible values: SALARY, UNEMPLOYMENT, CASH, GIG\_ECONOMY, RENTAL, CHILD\_SUPPORT, MILITARY, RETIREMENT, LONG\_TERM\_DISABILITY, BANK\_INTEREST, CASH\_DEPOSIT, TRANSFER\_FROM\_APPLICATION, TAX\_REFUND, BENEFIT\_OTHER, OTHER

**bank\_income->items->bank\_income\_sources->account\_id** (string)  
Plaid's unique identifier for the account.

**bank\_income->items->bank\_income\_sources->start\_date** (string)  
Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->items->bank\_income\_sources->end\_date** (string)  
Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->items->bank\_income\_sources->pay\_frequency** (string)  
The income pay frequency. Possible values: WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, DAILY, UNKNOWN

**bank\_income->items->bank\_income\_sources->total\_amount** (number)  
Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.

**bank\_income->items->bank\_income\_sources->transaction\_count** (integer)  
Number of transactions for the income source within the start and end date.

deprecated, number

**bank\_income->items->bank\_income\_sources->historical\_summary** (\[object\])  
Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total\_amounts instead.

**bank\_income->items->bank\_income\_sources->historical\_summary->iso\_currency\_code** (deprecated, nullable, string)  
The ISO 4217 currency code of the amount or balance. Please use total\_amounts instead.

**bank\_income->items->bank\_income\_sources->historical\_summary->unofficial\_currency\_code** (deprecated, nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use total\_amounts instead.

**bank\_income->items->bank\_income\_sources->historical\_summary->total\_amounts** (\[object\])  
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.

**bank\_income->items->bank\_income\_sources->historical\_summary->total\_amounts->amount** (number)  
Value of amount with up to 2 decimal places.

**bank\_income->items->bank\_income\_sources->historical\_summary->total\_amounts->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**bank\_income->items->bank\_income\_sources->historical\_summary->total\_amounts->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**bank\_income->items->bank\_income\_sources->historical\_summary->start\_date** (string)  
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->items->bank\_income\_sources->historical\_summary->end\_date** (string)  
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

number

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions** (\[object\])  
The settled value of the transaction, denominated in the transactions's currency as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->name** (string)  
The merchant name or transaction description.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**bank\_income->items->bank\_income\_sources->historical\_summary->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**bank\_income->items->last\_updated\_time** (string)  
The time when this Item's data was last retrieved from the financial institution. Format: date-time

**bank\_income->items->institution\_id** (string)  
The unique identifier of the institution associated with the Item.

**bank\_income->items->institution\_name** (string)  
The name of the institution associated with the Item.

**bank\_income->items->item\_id** (string)  
The unique identifier for the Item.

**bank\_income->bank\_income\_summary** (object)  
Summary for bank income across all income sources and items (max history of 730 days).

**bank\_income->bank\_income\_summary->total\_amount** (deprecated, number)  
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total\_amounts instead.

**bank\_income->bank\_income\_summary->iso\_currency\_code** (deprecated, nullable, string)  
The ISO 4217 currency code of the amount or balance. Please use total\_amounts instead.

**bank\_income->bank\_income\_summary->unofficial\_currency\_code** (deprecated, nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use total\_amounts instead.

**bank\_income->bank\_income\_summary->total\_amounts** (\[object\])  
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This can contain multiple amounts, with each amount denominated in one unique currency.

**bank\_income->bank\_income\_summary->total\_amounts->amount** (number)  
Value of amount with up to 2 decimal places.

**bank\_income->bank\_income\_summary->total\_amounts->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**bank\_income->bank\_income\_summary->total\_amounts->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**bank\_income->bank\_income\_summary->start\_date** (string)  
The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->bank\_income\_summary->end\_date** (string)  
The latest date in which all income sources identified by Plaid appear in the user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->bank\_income\_summary->income\_sources\_count** (integer)  
Number of income sources per end user.

**bank\_income->bank\_income\_summary->income\_categories\_count** (integer)  
Number of income categories per end user.

**bank\_income->bank\_income\_summary->income\_transactions\_count** (integer)  
Number of income transactions per end user.

deprecated, number

**bank\_income->bank\_income\_summary->historical\_summary** (\[object\])  
Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total\_amounts instead.

**bank\_income->bank\_income\_summary->historical\_summary->iso\_currency\_code** (deprecated, nullable, string)  
The ISO 4217 currency code of the amount or balance. Please use total\_amounts instead.

**bank\_income->bank\_income\_summary->historical\_summary->unofficial\_currency\_code** (deprecated, nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use total\_amounts instead.

**bank\_income->bank\_income\_summary->historical\_summary->total\_amounts** (\[object\])  
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.

**bank\_income->bank\_income\_summary->historical\_summary->total\_amounts->amount** (number)  
Value of amount with up to 2 decimal places.

**bank\_income->bank\_income\_summary->historical\_summary->total\_amounts->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**bank\_income->bank\_income\_summary->historical\_summary->total\_amounts->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**bank\_income->bank\_income\_summary->historical\_summary->start\_date** (string)  
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->bank\_income\_summary->historical\_summary->end\_date** (string)  
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: date

number

**bank\_income->bank\_income\_summary->historical\_summary->transactions** (\[object\])  
The settled value of the transaction, denominated in the transactions's currency as stated in iso\_currency\_code or unofficial\_currency\_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**bank\_income->bank\_income\_summary->historical\_summary->transactions->name** (string)  
The merchant name or transaction description.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->iso\_currency\_code** (nullable, string)  
The ISO 4217 currency code of the amount or balance.

**bank\_income->bank\_income\_summary->historical\_summary->transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the amount or balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**bank\_income->warnings** (\[object\])  
If data from the report was unable to be retrieved, the warnings will contain information about the error that caused the data to be incomplete.

**bank\_income->warnings->warning\_type** (string)  
The warning type which will always be BANK\_INCOME\_WARNING. Possible values: BANK\_INCOME\_WARNING

**bank\_income->warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning. IDENTITY\_UNAVAILABLE: Unable to extract identity for the Item TRANSACTIONS\_UNAVAILABLE: Unable to extract transactions for the Item ITEM\_UNAPPROVED: User exited flow before giving permission to share data for the Item REPORT\_DELETED: Report deleted due to customer or consumer request DATA\_UNAVAILABLE: No relevant data was found for the Item Possible values: IDENTITY\_UNAVAILABLE, TRANSACTIONS\_UNAVAILABLE, ITEM\_UNAPPROVED, REPORT\_DELETED, DATA\_UNAVAILABLE

**bank\_income->warnings->cause** (object)  
An error object and associated item\_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.

**bank\_income->warnings->cause->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INTERNAL\_SERVER\_ERROR, INSUFFICIENT\_CREDENTIALS, ITEM\_LOCKED, USER\_SETUP\_REQUIRED, COUNTRY\_NOT\_SUPPORTED, INSTITUTION\_DOWN, INSTITUTION\_NO\_LONGER\_SUPPORTED, INSTITUTION\_NOT\_RESPONDING, INVALID\_CREDENTIALS, INVALID\_MFA, INVALID\_SEND\_METHOD, ITEM\_LOGIN\_REQUIRED, MFA\_NOT\_SUPPORTED, NO\_ACCOUNTS, ITEM\_NOT\_SUPPORTED, ACCESS\_NOT\_GRANTED

**bank\_income->warnings->cause->error\_code** (string)  
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error\_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred.

**bank\_income->warnings->cause->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**bank\_income->warnings->cause->display\_message** (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.

**bank\_income->warnings->cause->item\_id** (string)  
The item\_id of the Item associated with this warning.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "bank_income": [
    {
      "bank_income_id": "dacc92a0-cb59-43a5-ba24-1b1c07a03f28",
      "bank_income_summary": {
        "end_date": "2024-08-21",
        "historical_summary": [
          {
            "end_date": "2024-08-21",
            "iso_currency_code": "USD",
            "start_date": "2024-08-06",
            "total_amount": 4090.14,
            "total_amounts": [
              {
                "amount": 4090.14,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "transactions": [
              {
                "amount": 120.12,
                "check_number": null,
                "date": "2024-08-07",
                "iso_currency_code": "USD",
                "name": "TEXAS OAG CHILD SUPPORT",
                "original_description": "TEXAS OAG CHILD SUPPORT",
                "transaction_id": "EZMmvwREqlSGmlRam7bzFKyBll3kJjU4xKm1w",
                "unofficial_currency_code": null
              },
              {
                "amount": 1525,
                "check_number": null,
                "date": "2024-08-08",
                "iso_currency_code": "USD",
                "name": "AIRBNB PAYMENTS PPD ID: 1234567890",
                "original_description": "AIRBNB PAYMENTS PPD ID: 1234567890",
                "transaction_id": "Wr6jzLwg1qs6ag9Xa8BrCpBAPPxnEXF6ZmjDR",
                "unofficial_currency_code": null
              },
              {
                "amount": 500,
                "check_number": null,
                "date": "2024-08-12",
                "iso_currency_code": "USD",
                "name": "TWC-BENEFITS/UI BENEFIT",
                "original_description": "TWC-BENEFITS/UI BENEFIT",
                "transaction_id": "Aj7Apx5bDyIA3VRl35yqC18wXXorBgI9rX5dp",
                "unofficial_currency_code": null
              },
              {
                "amount": 1000.7,
                "check_number": null,
                "date": "2024-08-15",
                "iso_currency_code": "USD",
                "name": "PLAID PAYROLL",
                "original_description": "PLAID PAYROLL",
                "transaction_id": "G1L9oybBrKSMPmBdPzXoFN8aGGE7gXC6MeoQB",
                "unofficial_currency_code": null
              },
              {
                "amount": 824.2,
                "check_number": null,
                "date": "2024-08-15",
                "iso_currency_code": "USD",
                "name": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890",
                "original_description": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890",
                "transaction_id": "nWLlwMm1qxi8DomvDXP3FaGjXX5bm9TAlyQnk",
                "unofficial_currency_code": null
              },
              {
                "amount": 120.12,
                "check_number": null,
                "date": "2024-08-21",
                "iso_currency_code": "USD",
                "name": "TEXAS OAG CHILD SUPPORT",
                "original_description": "TEXAS OAG CHILD SUPPORT",
                "transaction_id": "b7dkg6eQbPFQeRvVeZlxcqxZooa7nWSmb47dj",
                "unofficial_currency_code": null
              }
            ],
            "unofficial_currency_code": null
          }
        ],
        "income_categories_count": 5,
        "income_sources_count": 5,
        "income_transactions_count": 6,
        "iso_currency_code": "USD",
        "start_date": "2024-08-07",
        "total_amount": 4090.14,
        "total_amounts": [
          {
            "amount": 4090.14,
            "iso_currency_code": "USD",
            "unofficial_currency_code": null
          }
        ],
        "unofficial_currency_code": null
      },
      "days_requested": 15,
      "generated_time": "2024-08-21T18:10:46.293199Z",
      "items": [
        {
          "bank_income_accounts": [
            {
              "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5",
              "mask": "9217",
              "name": "Checking",
              "official_name": "Plaid checking",
              "owners": [
                {
                  "addresses": [],
                  "emails": [],
                  "names": [
                    "Jane Doe"
                  ],
                  "phone_numbers": []
                }
              ],
              "subtype": "checking",
              "type": "depository"
            }
          ],
          "bank_income_sources": [
            {
              "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5",
              "end_date": "2024-08-15",
              "historical_summary": [
                {
                  "end_date": "2024-08-21",
                  "iso_currency_code": "USD",
                  "start_date": "2024-08-06",
                  "total_amount": 1000.7,
                  "total_amounts": [
                    {
                      "amount": 1000.7,
                      "iso_currency_code": "USD",
                      "unofficial_currency_code": null
                    }
                  ],
                  "transactions": [
                    {
                      "amount": 1000.7,
                      "check_number": null,
                      "date": "2024-08-15",
                      "iso_currency_code": "USD",
                      "name": "PLAID PAYROLL",
                      "original_description": "PLAID PAYROLL",
                      "transaction_id": "G1L9oybBrKSMPmBdPzXoFN8aGGE7gXC6MeoQB",
                      "unofficial_currency_code": null
                    }
                  ],
                  "unofficial_currency_code": null
                }
              ],
              "income_category": "SALARY",
              "income_description": "PLAID PAYROLL",
              "income_source_id": "0e9d6fbc-29de-4225-9843-2f71e02a54d1",
              "pay_frequency": "UNKNOWN",
              "start_date": "2024-08-15",
              "total_amount": 1000.7,
              "transaction_count": 1
            },
            {
              "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5",
              "end_date": "2024-08-15",
              "historical_summary": [
                {
                  "end_date": "2024-08-21",
                  "iso_currency_code": "USD",
                  "start_date": "2024-08-06",
                  "total_amount": 824.2,
                  "total_amounts": [
                    {
                      "amount": 824.2,
                      "iso_currency_code": "USD",
                      "unofficial_currency_code": null
                    }
                  ],
                  "transactions": [
                    {
                      "amount": 824.2,
                      "check_number": null,
                      "date": "2024-08-15",
                      "iso_currency_code": "USD",
                      "name": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890",
                      "original_description": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890",
                      "transaction_id": "nWLlwMm1qxi8DomvDXP3FaGjXX5bm9TAlyQnk",
                      "unofficial_currency_code": null
                    }
                  ],
                  "unofficial_currency_code": null
                }
              ],
              "income_category": "LONG_TERM_DISABILITY",
              "income_description": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890",
              "income_source_id": "88bc00d8-2bb1-42d0-a054-db3f20948283",
              "pay_frequency": "UNKNOWN",
              "start_date": "2024-08-15",
              "total_amount": 824.2,
              "transaction_count": 1
            },
            {
              "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5",
              "end_date": "2024-08-08",
              "historical_summary": [
                {
                  "end_date": "2024-08-21",
                  "iso_currency_code": "USD",
                  "start_date": "2024-08-06",
                  "total_amount": 1525,
                  "total_amounts": [
                    {
                      "amount": 1525,
                      "iso_currency_code": "USD",
                      "unofficial_currency_code": null
                    }
                  ],
                  "transactions": [
                    {
                      "amount": 1525,
                      "check_number": null,
                      "date": "2024-08-08",
                      "iso_currency_code": "USD",
                      "name": "AIRBNB PAYMENTS PPD ID: 1234567890",
                      "original_description": "AIRBNB PAYMENTS PPD ID: 1234567890",
                      "transaction_id": "Wr6jzLwg1qs6ag9Xa8BrCpBAPPxnEXF6ZmjDR",
                      "unofficial_currency_code": null
                    }
                  ],
                  "unofficial_currency_code": null
                }
              ],
              "income_category": "RENTAL",
              "income_description": "AIRBNB PAYMENTS PPD ID: 1234567890",
              "income_source_id": "063689af-7299-4327-b71f-9d8849a40c0e",
              "pay_frequency": "UNKNOWN",
              "start_date": "2024-08-08",
              "total_amount": 1525,
              "transaction_count": 1
            },
            {
              "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5",
              "end_date": "2024-08-12",
              "historical_summary": [
                {
                  "end_date": "2024-08-21",
                  "iso_currency_code": "USD",
                  "start_date": "2024-08-06",
                  "total_amount": 500,
                  "total_amounts": [
                    {
                      "amount": 500,
                      "iso_currency_code": "USD",
                      "unofficial_currency_code": null
                    }
                  ],
                  "transactions": [
                    {
                      "amount": 500,
                      "check_number": null,
                      "date": "2024-08-12",
                      "iso_currency_code": "USD",
                      "name": "TWC-BENEFITS/UI BENEFIT",
                      "original_description": "TWC-BENEFITS/UI BENEFIT",
                      "transaction_id": "Aj7Apx5bDyIA3VRl35yqC18wXXorBgI9rX5dp",
                      "unofficial_currency_code": null
                    }
                  ],
                  "unofficial_currency_code": null
                }
              ],
              "income_category": "UNEMPLOYMENT",
              "income_description": "TWC-BENEFITS/UI BENEFIT",
              "income_source_id": "ce160170-49d0-4811-b58e-cb4878d05f83",
              "pay_frequency": "UNKNOWN",
              "start_date": "2024-08-12",
              "total_amount": 500,
              "transaction_count": 1
            },
            {
              "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5",
              "end_date": "2024-08-21",
              "historical_summary": [
                {
                  "end_date": "2024-08-21",
                  "iso_currency_code": "USD",
                  "start_date": "2024-08-06",
                  "total_amount": 240.24,
                  "total_amounts": [
                    {
                      "amount": 240.24,
                      "iso_currency_code": "USD",
                      "unofficial_currency_code": null
                    }
                  ],
                  "transactions": [
                    {
                      "amount": 120.12,
                      "check_number": null,
                      "date": "2024-08-07",
                      "iso_currency_code": "USD",
                      "name": "TEXAS OAG CHILD SUPPORT",
                      "original_description": "TEXAS OAG CHILD SUPPORT",
                      "transaction_id": "EZMmvwREqlSGmlRam7bzFKyBll3kJjU4xKm1w",
                      "unofficial_currency_code": null
                    },
                    {
                      "amount": 120.12,
                      "check_number": null,
                      "date": "2024-08-21",
                      "iso_currency_code": "USD",
                      "name": "TEXAS OAG CHILD SUPPORT",
                      "original_description": "TEXAS OAG CHILD SUPPORT",
                      "transaction_id": "b7dkg6eQbPFQeRvVeZlxcqxZooa7nWSmb47dj",
                      "unofficial_currency_code": null
                    }
                  ],
                  "unofficial_currency_code": null
                }
              ],
              "income_category": "CHILD_SUPPORT",
              "income_description": "TEXAS OAG CHILD SUPPORT",
              "income_source_id": "c8e1576e-9de4-47b4-ad55-3f7b068cc863",
              "pay_frequency": "UNKNOWN",
              "start_date": "2024-08-07",
              "total_amount": 240.24,
              "transaction_count": 2
            }
          ],
          "institution_id": "ins_20",
          "institution_name": "Citizens Bank",
          "item_id": "L8EKo4GydxSKmJQGmXyPuDkeNn4rg9fP3MKLv",
          "last_updated_time": "2024-08-21T18:10:47.367335Z"
        }
      ]
    }
  ],
  "request_id": "MLM1fFu4fbVg7KR"
}
```

\=\*=\*=\*=

#### /credit/bank\_income/pdf/get 

#### Retrieve information from the bank accounts used for income verification in PDF format 

[/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) returns the most recent bank income report for a specified user in PDF format. A single report corresponds to all institutions linked in a single Link session. To include multiple institutions in a single report, use [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) .

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

```javascript
const request: CreditBankIncomePDFGetRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
};


try {
  const response = await client.creditBankIncomePdfGet(request, {
    responseType: 'arraybuffer',
  });
  const pdf = response.buffer.toString('base64');
} catch (error) {
  // handle error
}
```

##### Response 

This endpoint returns binary PDF data. [View a sample Bank Income PDF.](https://plaid.com/documents/sample-bank-income.pdf)

\=\*=\*=\*=

#### /credit/bank\_income/refresh 

#### Refresh a user's bank income information 

[/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) refreshes the most recent bank income report data for a specific user. If the most recent bank income report is no longer valid (i.e. deleted), the endpoint will refresh the most recent valid report instead.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**options** (object)  
An optional object for /credit/bank\_income/refresh request options.

**options->days\_requested** (integer)  
How many days of data to include in the refresh. If not specified, this will default to the days requested in the most recently generated bank income report for the user.

```javascript
const request: CreditBankIncomeRefreshRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
  options: {
    days_requested: 120,
  },
};


try {
  const response = await client.creditBankIncomeRefresh(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "LhQf0THi8SH1yJm"
}
```

\=\*=\*=\*=

#### /credit/bank\_statements/uploads/get 

#### Retrieve data for a user's uploaded bank statements 

[/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) returns parsed data from bank statements uploaded by users as part of the Document Income flow. If your account is not enabled for Document Parsing, contact your account manager to request access.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**options** (object)  
An optional object for /credit/bank\_statements/uploads/get request options.

**options->item\_ids** (\[string\])  
An array of item\_ids whose bank statements information is returned. Each item\_id should uniquely identify a bank statements uploaded item. If this field is not provided, all item\_ids associated with the user\_token will returned in the response.

```javascript
const request: CreditBankStatementsUploadsGetRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
};


try {
  const response = await client.creditBankStatementsUploadsGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**items** (\[object\])  
Array of bank statement upload items.

**items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**items->bank\_statements** (\[object\])  
An array of transactions appearing on the bank statement.

nullable, number

**items->bank\_statements->transactions** (\[object\])  
The value of the transaction. A negative amount indicates that money moved into the account (such as a paycheck being deposited).

**items->bank\_statements->transactions->date** (nullable, string)  
The date of when the transaction was made, in ISO 8601 format (YYYY-MM-DD). Format: date

**items->bank\_statements->transactions->original\_description** (nullable, string)  
The raw description of the transaction as it appears on the bank statement.

**items->bank\_statements->transactions->account\_id** (nullable, string)  
The unique id of the bank account that this transaction occurs in

**items->bank\_statements->document\_metadata** (object)  
Object representing metadata pertaining to the document.

**items->bank\_statements->document\_metadata->name** (string)  
The name of the document.

**items->bank\_statements->document\_metadata->document\_type** (nullable, string)  
The type of document. PAYSTUB: A paystub. BANK\_STATEMENT: A bank statement. US\_TAX\_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. US\_MILITARY\_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military. US\_MILITARY\_LES: A Leave and Earnings Statement (LES) issued by the US military. US\_MILITARY\_CLES: A Civilian Leave and Earnings Statement (CLES) issued by the US military. GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. PLAID\_GENERATED\_PAYSTUB\_PDF: Used to indicate that the PDF for the paystub was generated by Plaid. NONE: Used to indicate that there is no underlying document for the data. UNKNOWN: Document type could not be determined. Possible values: UNKNOWN, PAYSTUB, BANK\_STATEMENT, US\_TAX\_W2, US\_MILITARY\_ERAS, US\_MILITARY\_LES, US\_MILITARY\_CLES, GIG, PLAID\_GENERATED\_PAYSTUB\_PDF, NONE

**items->bank\_statements->document\_metadata->download\_url** (nullable, string)  
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub. For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll\_income/get again.

**items->bank\_statements->document\_metadata->status** (nullable, string)  
The processing status of the document. PROCESSING\_COMPLETE: The document was successfully processed. DOCUMENT\_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: UNKNOWN, PROCESSING\_COMPLETE, DOCUMENT\_ERROR, null

**items->bank\_statements->document\_metadata->page\_count** (nullable, integer)  
The number of pages of the uploaded document (if available).

**items->bank\_statements->document\_metadata->error\_message** (nullable, string)  
The reason why a failure occurred during document processing (if available).

**items->bank\_statements->document\_id** (nullable, string)  
An identifier of the document referenced by the document metadata.

**items->bank\_statements->bank\_accounts** (\[object\])  
An array of bank accounts associated with the uploaded bank statement.

**items->bank\_statements->bank\_accounts->name** (nullable, string)  
The name of the bank account

**items->bank\_statements->bank\_accounts->bank\_name** (nullable, string)  
The name of the bank institution.

**items->bank\_statements->bank\_accounts->account\_type** (nullable, string)  
The type of the bank account.

**items->bank\_statements->bank\_accounts->account\_number** (nullable, string)  
The bank account number.

**items->bank\_statements->bank\_accounts->owner** (object)  
An object containing data about the owner of the bank account for the uploaded bank statement.

**items->bank\_statements->bank\_accounts->owner->name** (nullable, string)  
The name of the account owner

**items->bank\_statements->bank\_accounts->owner->address** (object)  
Address on the uploaded bank statement

**items->bank\_statements->bank\_accounts->owner->address->city** (nullable, string)  
The full city name.

**items->bank\_statements->bank\_accounts->owner->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->bank\_statements->bank\_accounts->owner->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->bank\_statements->bank\_accounts->owner->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->bank\_statements->bank\_accounts->owner->address->street** (nullable, string)  
The full street address.

**items->bank\_statements->bank\_accounts->periods** (\[object\])  
An array of period objects, containing more data on the overall period of the statement.

**items->bank\_statements->bank\_accounts->periods->start\_date** (nullable, string)  
The start date of the statement period in ISO 8601 format (YYYY-MM-DD). Format: date

**items->bank\_statements->bank\_accounts->periods->end\_date** (nullable, string)  
The end date of the statement period in ISO 8601 format (YYYY-MM-DD). Format: date

**items->bank\_statements->bank\_accounts->periods->starting\_balance** (nullable, number)  
The starting balance of the bank account for the period.

**items->bank\_statements->bank\_accounts->periods->ending\_balance** (nullable, number)  
The ending balance of the bank account for the period.

**items->bank\_statements->bank\_accounts->account\_id** (nullable, string)  
The unique id of the bank account

**items->status** (nullable, object)  
Details about the status of the payroll item.

**items->status->processing\_status** (nullable, string)  
Denotes the processing status for the verification. UNKNOWN: The processing status could not be determined. PROCESSING\_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved. PROCESSING: The verification is still processing. The data is not available yet. FAILED: The processing failed to complete successfully. APPROVAL\_STATUS\_PENDING: The processing has completed but the user has not yet approved the sharing of the data. Possible values: UNKNOWN, PROCESSING\_COMPLETE, PROCESSING, FAILED, APPROVAL\_STATUS\_PENDING

**items->updated\_at** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "items": [
    {
      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
      "bank_statements": [
        {
          "transactions": [
            {
              "amount": -1000,
              "date": "2023-01-01",
              "original_description": "PAYCHECK",
              "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d"
            }
          ],
          "document_metadata": {
            "document_type": "BANK_STATEMENT",
            "name": "statement_01.pdf",
            "status": "PROCESSING_COMPLETE",
            "download_url": null,
            "page_count": 2
          },
          "document_id": "2jkflanbd",
          "bank_accounts": [
            {
              "name": "CHASE CHECKING",
              "bank_name": "CHASE",
              "account_type": "CHECKING",
              "account_number": "000009752",
              "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d",
              "owner": {
                "name": "JANE DOE",
                "address": {
                  "postal_code": "94133",
                  "country": "US",
                  "region": "CA",
                  "city": "SAN FRANCISCO",
                  "street": "2140 TAYLOR ST"
                }
              },
              "periods": [
                {
                  "start_date": "2023-01-01",
                  "end_date": "2023-02-01",
                  "starting_balance": 2500,
                  "ending_balance": 3500
                }
              ]
            }
          ]
        }
      ],
      "status": {
        "processing_status": "PROCESSING_COMPLETE"
      },
      "updated_at": "2023-02-01T21:14:54Z"
    }
  ],
  "request_id": "LhQf0THi8SH1yJm"
}
```

\=\*=\*=\*=

#### /credit/payroll\_income/get 

#### Retrieve a user's payroll information 

This endpoint gets payroll income information for a specific user, either as a result of the user connecting to their payroll provider or uploading a pay related document.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

**options** (object)  
An optional object for /credit/payroll\_income/get request options.

**options->item\_ids** (\[string\])  
An array of item\_ids whose payroll information is returned. Each item\_id should uniquely identify a payroll income item. If this field is not provided, all item\_ids associated with the user\_token will returned in the response.

```javascript
const request: CreditPayrollIncomeGetRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
};


try {
  const response = await client.creditPayrollIncomeGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**items** (\[object\])  
Array of payroll items.

**items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**items->institution\_id** (string)  
The unique identifier of the institution associated with the Item.

**items->institution\_name** (string)  
The name of the institution associated with the Item.

nullable, string

**items->accounts** (\[object\])  
ID of the payroll provider account.

**items->accounts->rate\_of\_pay** (object)  
An object representing the rate at which an individual is paid.

**items->accounts->rate\_of\_pay->pay\_rate** (nullable, string)  
The rate at which an employee is paid. Possible values: ANNUAL, HOURLY, CONTRACT, WEEKLY, BIWEEKLY, MONTHLY, SEMI\_MONTHLY, DAILY, COMMISSION, OTHER, null

**items->accounts->rate\_of\_pay->pay\_amount** (nullable, number)  
The amount at which an employee is paid. Format: double

**items->accounts->pay\_frequency** (nullable, string)  
The frequency at which an individual is paid. Possible values: DAILY, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, CONTRACT, QUARTERLY, SEMI\_ANNUALLY, ANNUALLY, OTHER, null

nullable, string

**items->payroll\_income** (\[object\])  
ID of the payroll provider account.

**items->payroll\_income->pay\_stubs** (\[object\])  
Array of pay stubs for the user.

**items->payroll\_income->pay\_stubs->deductions** (object)  
An object with the deduction information found on a pay stub.

nullable, number

**items->payroll\_income->pay\_stubs->deductions->breakdown** (\[object\])  
Raw amount of the deduction Format: double

**items->payroll\_income->pay\_stubs->deductions->breakdown->description** (nullable, string)  
Description of the deduction line item

**items->payroll\_income->pay\_stubs->deductions->breakdown->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the line item. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->deductions->breakdown->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the line item. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->pay\_stubs->deductions->breakdown->ytd\_amount** (nullable, number)  
The year-to-date amount of the deduction Format: double

**items->payroll\_income->pay\_stubs->deductions->total** (object)  
An object representing the total deductions for the pay period

**items->payroll\_income->pay\_stubs->deductions->total->current\_amount** (nullable, number)  
Raw amount of the deduction Format: double

**items->payroll\_income->pay\_stubs->deductions->total->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the line item. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->deductions->total->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the line item. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->pay\_stubs->deductions->total->ytd\_amount** (nullable, number)  
The year-to-date total amount of the deductions Format: double

**items->payroll\_income->pay\_stubs->document\_id** (nullable, string)  
An identifier of the document referenced by the document metadata.

**items->payroll\_income->pay\_stubs->document\_metadata** (object)  
Object representing metadata pertaining to the document.

**items->payroll\_income->pay\_stubs->document\_metadata->name** (string)  
The name of the document.

**items->payroll\_income->pay\_stubs->document\_metadata->document\_type** (nullable, string)  
The type of document. PAYSTUB: A paystub. BANK\_STATEMENT: A bank statement. US\_TAX\_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. US\_MILITARY\_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military. US\_MILITARY\_LES: A Leave and Earnings Statement (LES) issued by the US military. US\_MILITARY\_CLES: A Civilian Leave and Earnings Statement (CLES) issued by the US military. GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. PLAID\_GENERATED\_PAYSTUB\_PDF: Used to indicate that the PDF for the paystub was generated by Plaid. NONE: Used to indicate that there is no underlying document for the data. UNKNOWN: Document type could not be determined. Possible values: UNKNOWN, PAYSTUB, BANK\_STATEMENT, US\_TAX\_W2, US\_MILITARY\_ERAS, US\_MILITARY\_LES, US\_MILITARY\_CLES, GIG, PLAID\_GENERATED\_PAYSTUB\_PDF, NONE

**items->payroll\_income->pay\_stubs->document\_metadata->download\_url** (nullable, string)  
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub. For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll\_income/get again.

**items->payroll\_income->pay\_stubs->document\_metadata->status** (nullable, string)  
The processing status of the document. PROCESSING\_COMPLETE: The document was successfully processed. DOCUMENT\_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: UNKNOWN, PROCESSING\_COMPLETE, DOCUMENT\_ERROR, null

**items->payroll\_income->pay\_stubs->document\_metadata->page\_count** (nullable, integer)  
The number of pages of the uploaded document (if available).

**items->payroll\_income->pay\_stubs->document\_metadata->error\_message** (nullable, string)  
The reason why a failure occurred during document processing (if available).

**items->payroll\_income->pay\_stubs->earnings** (object)  
An object representing both a breakdown of earnings on a pay stub and the total earnings.

nullable, string

**items->payroll\_income->pay\_stubs->earnings->breakdown** (\[object\])  
Commonly used term to describe the earning line item. Possible values: BONUS, COMMISSION, OVERTIME, PAID\_TIME\_OFF, REGULAR\_PAY, VACATION, BASIC\_ALLOWANCE\_HOUSING, BASIC\_ALLOWANCE\_SUBSISTENCE, OTHER, ALLOWANCE, BEREAVEMENT, HOLIDAY\_PAY, JURY\_DUTY, LEAVE, LONG\_TERM\_DISABILITY\_PAY, MILITARY\_PAY, PER\_DIEM, REFERRAL\_BONUS, REIMBURSEMENTS, RETENTION\_BONUS, RETROACTIVE\_PAY, SEVERANCE\_PAY, SHIFT\_DIFFERENTIAL, SHORT\_TERM\_DISABILITY\_PAY, SICK\_PAY, SIGNING\_BONUS, TIPS\_INCOME, RETIREMENT, GIG\_ECONOMY, STOCK\_COMPENSATION, null

**items->payroll\_income->pay\_stubs->earnings->breakdown->current\_amount** (nullable, number)  
Raw amount of the earning line item. Format: double

**items->payroll\_income->pay\_stubs->earnings->breakdown->description** (nullable, string)  
Description of the earning line item.

**items->payroll\_income->pay\_stubs->earnings->breakdown->hours** (nullable, number)  
Number of hours applicable for this earning.

**items->payroll\_income->pay\_stubs->earnings->breakdown->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the line item. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->earnings->breakdown->rate** (nullable, number)  
Hourly rate applicable for this earning. Format: double

**items->payroll\_income->pay\_stubs->earnings->breakdown->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the line item. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->pay\_stubs->earnings->breakdown->ytd\_amount** (nullable, number)  
The year-to-date amount of the deduction. Format: double

**items->payroll\_income->pay\_stubs->earnings->total** (object)  
An object representing both the current pay period and year to date amount for an earning category.

**items->payroll\_income->pay\_stubs->earnings->total->current\_amount** (nullable, number)  
Total amount of the earnings for this pay period. Format: double

**items->payroll\_income->pay\_stubs->earnings->total->hours** (nullable, number)  
Total number of hours worked for this pay period.

**items->payroll\_income->pay\_stubs->earnings->total->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the line item. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->earnings->total->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the security. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->pay\_stubs->earnings->total->ytd\_amount** (nullable, number)  
The total year-to-date amount of the earnings. Format: double

**items->payroll\_income->pay\_stubs->employee** (object)  
Data about the employee.

**items->payroll\_income->pay\_stubs->employee->address** (object)  
Address on the pay stub.

**items->payroll\_income->pay\_stubs->employee->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->pay\_stubs->employee->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->pay\_stubs->employee->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->pay\_stubs->employee->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->pay\_stubs->employee->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->pay\_stubs->employee->name** (nullable, string)  
The name of the employee.

**items->payroll\_income->pay\_stubs->employee->marital\_status** (nullable, string)  
Marital status of the employee - either SINGLE or MARRIED or NOT LISTED. Possible values: SINGLE, MARRIED, NOT LISTED, null

**items->payroll\_income->pay\_stubs->employee->taxpayer\_id** (object)  
Taxpayer ID of the individual receiving the paystub.

**items->payroll\_income->pay\_stubs->employee->taxpayer\_id->id\_type** (nullable, string)  
Type of ID, e.g. 'SSN'.

**items->payroll\_income->pay\_stubs->employee->taxpayer\_id->id\_mask** (nullable, string)  
ID mask; i.e. last 4 digits of the taxpayer ID.

**items->payroll\_income->pay\_stubs->employer** (object)  
Information about the employer on the pay stub.

**items->payroll\_income->pay\_stubs->employer->address** (object)  
Address on the pay stub.

**items->payroll\_income->pay\_stubs->employer->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->pay\_stubs->employer->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->pay\_stubs->employer->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->pay\_stubs->employer->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->pay\_stubs->employer->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->pay\_stubs->employer->name** (nullable, string)  
The name of the employer on the pay stub.

**items->payroll\_income->pay\_stubs->net\_pay** (object)  
An object representing information about the net pay amount on the pay stub.

**items->payroll\_income->pay\_stubs->net\_pay->current\_amount** (nullable, number)  
Raw amount of the net pay for the pay period. Format: double

**items->payroll\_income->pay\_stubs->net\_pay->description** (nullable, string)  
Description of the net pay.

**items->payroll\_income->pay\_stubs->net\_pay->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the net pay. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->net\_pay->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the net pay. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->pay\_stubs->net\_pay->ytd\_amount** (nullable, number)  
The year-to-date amount of the net pay. Format: double

**items->payroll\_income->pay\_stubs->pay\_period\_details** (object)  
Details about the pay period.

**items->payroll\_income->pay\_stubs->pay\_period\_details->pay\_amount** (nullable, number)  
The amount of the paycheck. Format: double

nullable, string

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown** (\[object\])  
Name of the account for the given distribution.

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown->bank\_name** (nullable, string)  
The name of the bank that the payment is being deposited to.

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown->current\_amount** (nullable, number)  
The amount distributed to this account. Format: double

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the net pay. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown->mask** (nullable, string)  
The last 2-4 alphanumeric characters of an account's official account number.

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown->type** (nullable, string)  
Type of the account that the paystub was sent to (e.g. 'checking').

**items->payroll\_income->pay\_stubs->pay\_period\_details->distribution\_breakdown->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the net pay. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->pay\_stubs->pay\_period\_details->end\_date** (nullable, string)  
The date on which the pay period ended, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**items->payroll\_income->pay\_stubs->pay\_period\_details->gross\_earnings** (nullable, number)  
Total earnings before tax/deductions. Format: double

**items->payroll\_income->pay\_stubs->pay\_period\_details->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the net pay. Always null if unofficial\_currency\_code is non-null.

**items->payroll\_income->pay\_stubs->pay\_period\_details->pay\_date** (nullable, string)  
The date on which the pay stub was issued, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**items->payroll\_income->pay\_stubs->pay\_period\_details->pay\_frequency** (nullable, string)  
The frequency at which an individual is paid. Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, null

**items->payroll\_income->pay\_stubs->pay\_period\_details->pay\_basis** (string)  
The explicit pay basis on the paystub (if present). Possible values: SALARY, HOURLY, COMMISSION

**items->payroll\_income->pay\_stubs->pay\_period\_details->start\_date** (nullable, string)  
The date on which the pay period started, in ISO 8601 format ("yyyy-mm-dd"). Format: date

**items->payroll\_income->pay\_stubs->pay\_period\_details->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the net pay. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**items->payroll\_income->w2s** (\[object\])  
Array of tax form W-2s.

**items->payroll\_income->w2s->document\_metadata** (object)  
Object representing metadata pertaining to the document.

**items->payroll\_income->w2s->document\_metadata->name** (string)  
The name of the document.

**items->payroll\_income->w2s->document\_metadata->document\_type** (nullable, string)  
The type of document. PAYSTUB: A paystub. BANK\_STATEMENT: A bank statement. US\_TAX\_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. US\_MILITARY\_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military. US\_MILITARY\_LES: A Leave and Earnings Statement (LES) issued by the US military. US\_MILITARY\_CLES: A Civilian Leave and Earnings Statement (CLES) issued by the US military. GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. PLAID\_GENERATED\_PAYSTUB\_PDF: Used to indicate that the PDF for the paystub was generated by Plaid. NONE: Used to indicate that there is no underlying document for the data. UNKNOWN: Document type could not be determined. Possible values: UNKNOWN, PAYSTUB, BANK\_STATEMENT, US\_TAX\_W2, US\_MILITARY\_ERAS, US\_MILITARY\_LES, US\_MILITARY\_CLES, GIG, PLAID\_GENERATED\_PAYSTUB\_PDF, NONE

**items->payroll\_income->w2s->document\_metadata->download\_url** (nullable, string)  
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub. For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll\_income/get again.

**items->payroll\_income->w2s->document\_metadata->status** (nullable, string)  
The processing status of the document. PROCESSING\_COMPLETE: The document was successfully processed. DOCUMENT\_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: UNKNOWN, PROCESSING\_COMPLETE, DOCUMENT\_ERROR, null

**items->payroll\_income->w2s->document\_metadata->page\_count** (nullable, integer)  
The number of pages of the uploaded document (if available).

**items->payroll\_income->w2s->document\_metadata->error\_message** (nullable, string)  
The reason why a failure occurred during document processing (if available).

**items->payroll\_income->w2s->document\_id** (string)  
An identifier of the document referenced by the document metadata.

**items->payroll\_income->w2s->employer** (object)  
Information about the employer on the pay stub.

**items->payroll\_income->w2s->employer->address** (object)  
Address on the pay stub.

**items->payroll\_income->w2s->employer->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->w2s->employer->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->w2s->employer->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->w2s->employer->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->w2s->employer->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->w2s->employer->name** (nullable, string)  
The name of the employer on the pay stub.

**items->payroll\_income->w2s->employee** (object)  
Data about the employee.

**items->payroll\_income->w2s->employee->address** (object)  
Address on the pay stub.

**items->payroll\_income->w2s->employee->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->w2s->employee->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->w2s->employee->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->w2s->employee->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->w2s->employee->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->w2s->employee->name** (nullable, string)  
The name of the employee.

**items->payroll\_income->w2s->employee->marital\_status** (nullable, string)  
Marital status of the employee - either SINGLE or MARRIED or NOT LISTED. Possible values: SINGLE, MARRIED, NOT LISTED, null

**items->payroll\_income->w2s->employee->taxpayer\_id** (object)  
Taxpayer ID of the individual receiving the paystub.

**items->payroll\_income->w2s->employee->taxpayer\_id->id\_type** (nullable, string)  
Type of ID, e.g. 'SSN'.

**items->payroll\_income->w2s->employee->taxpayer\_id->id\_mask** (nullable, string)  
ID mask; i.e. last 4 digits of the taxpayer ID.

**items->payroll\_income->w2s->tax\_year** (nullable, string)  
The tax year of the W2 document.

**items->payroll\_income->w2s->employer\_id\_number** (nullable, string)  
An employee identification number or EIN.

**items->payroll\_income->w2s->wages\_tips\_other\_comp** (nullable, string)  
Wages from tips and other compensation.

**items->payroll\_income->w2s->federal\_income\_tax\_withheld** (nullable, string)  
Federal income tax withheld for the tax year.

**items->payroll\_income->w2s->social\_security\_wages** (nullable, string)  
Wages from social security.

**items->payroll\_income->w2s->social\_security\_tax\_withheld** (nullable, string)  
Social security tax withheld for the tax year.

**items->payroll\_income->w2s->medicare\_wages\_and\_tips** (nullable, string)  
Wages and tips from medicare.

**items->payroll\_income->w2s->medicare\_tax\_withheld** (nullable, string)  
Medicare tax withheld for the tax year.

**items->payroll\_income->w2s->social\_security\_tips** (nullable, string)  
Tips from social security.

**items->payroll\_income->w2s->allocated\_tips** (nullable, string)  
Allocated tips.

**items->payroll\_income->w2s->box\_9** (nullable, string)  
Contents from box 9 on the W2.

**items->payroll\_income->w2s->dependent\_care\_benefits** (nullable, string)  
Dependent care benefits.

**items->payroll\_income->w2s->nonqualified\_plans** (nullable, string)  
Nonqualified plans.

nullable, string

**items->payroll\_income->w2s->box\_12** (\[object\])  
W2 Box 12 code.

**items->payroll\_income->w2s->box\_12->amount** (nullable, string)  
W2 Box 12 amount.

**items->payroll\_income->w2s->statutory\_employee** (nullable, string)  
Statutory employee.

**items->payroll\_income->w2s->retirement\_plan** (nullable, string)  
Retirement plan.

**items->payroll\_income->w2s->third\_party\_sick\_pay** (nullable, string)  
Third party sick pay.

**items->payroll\_income->w2s->other** (nullable, string)  
Other.

nullable, string

**items->payroll\_income->w2s->state\_and\_local\_wages** (\[object\])  
State associated with the wage.

**items->payroll\_income->w2s->state\_and\_local\_wages->employer\_state\_id\_number** (nullable, string)  
State identification number of the employer.

**items->payroll\_income->w2s->state\_and\_local\_wages->state\_wages\_tips** (nullable, string)  
Wages and tips from the specified state.

**items->payroll\_income->w2s->state\_and\_local\_wages->state\_income\_tax** (nullable, string)  
Income tax from the specified state.

**items->payroll\_income->w2s->state\_and\_local\_wages->local\_wages\_tips** (nullable, string)  
Wages and tips from the locality.

**items->payroll\_income->w2s->state\_and\_local\_wages->local\_income\_tax** (nullable, string)  
Income tax from the locality.

**items->payroll\_income->w2s->state\_and\_local\_wages->locality\_name** (nullable, string)  
Name of the locality.

**items->payroll\_income->form1099s** (\[object\])  
Array of tax form 1099s.

**items->payroll\_income->form1099s->document\_id** (nullable, string)  
An identifier of the document referenced by the document metadata.

**items->payroll\_income->form1099s->document\_metadata** (object)  
Object representing metadata pertaining to the document.

**items->payroll\_income->form1099s->document\_metadata->name** (string)  
The name of the document.

**items->payroll\_income->form1099s->document\_metadata->document\_type** (nullable, string)  
The type of document. PAYSTUB: A paystub. BANK\_STATEMENT: A bank statement. US\_TAX\_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. US\_MILITARY\_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military. US\_MILITARY\_LES: A Leave and Earnings Statement (LES) issued by the US military. US\_MILITARY\_CLES: A Civilian Leave and Earnings Statement (CLES) issued by the US military. GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. PLAID\_GENERATED\_PAYSTUB\_PDF: Used to indicate that the PDF for the paystub was generated by Plaid. NONE: Used to indicate that there is no underlying document for the data. UNKNOWN: Document type could not be determined. Possible values: UNKNOWN, PAYSTUB, BANK\_STATEMENT, US\_TAX\_W2, US\_MILITARY\_ERAS, US\_MILITARY\_LES, US\_MILITARY\_CLES, GIG, PLAID\_GENERATED\_PAYSTUB\_PDF, NONE

**items->payroll\_income->form1099s->document\_metadata->download\_url** (nullable, string)  
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub. For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll\_income/get again.

**items->payroll\_income->form1099s->document\_metadata->status** (nullable, string)  
The processing status of the document. PROCESSING\_COMPLETE: The document was successfully processed. DOCUMENT\_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: UNKNOWN, PROCESSING\_COMPLETE, DOCUMENT\_ERROR, null

**items->payroll\_income->form1099s->document\_metadata->page\_count** (nullable, integer)  
The number of pages of the uploaded document (if available).

**items->payroll\_income->form1099s->document\_metadata->error\_message** (nullable, string)  
The reason why a failure occurred during document processing (if available).

**items->payroll\_income->form1099s->form\_1099\_type** (string)  
Form 1099 Type Possible values: FORM\_1099\_TYPE\_UNKNOWN, FORM\_1099\_TYPE\_MISC, FORM\_1099\_TYPE\_K

**items->payroll\_income->form1099s->recipient** (object)  
An object representing a recipient used in both 1099-K and 1099-MISC tax documents.

**items->payroll\_income->form1099s->recipient->address** (object)  
Address on the pay stub.

**items->payroll\_income->form1099s->recipient->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->form1099s->recipient->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->form1099s->recipient->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->form1099s->recipient->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->form1099s->recipient->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->form1099s->recipient->name** (nullable, string)  
Name of recipient.

**items->payroll\_income->form1099s->recipient->tin** (nullable, string)  
Tax identification number of recipient.

**items->payroll\_income->form1099s->recipient->account\_number** (nullable, string)  
Account number number of recipient.

**items->payroll\_income->form1099s->recipient->facta\_filing\_requirement** (nullable, string)  
Checked if FACTA is a filing requirement. Possible values: CHECKED, NOT CHECKED

**items->payroll\_income->form1099s->recipient->second\_tin\_exists** (nullable, string)  
Checked if 2nd TIN exists. Possible values: CHECKED, NOT CHECKED

**items->payroll\_income->form1099s->payer** (object)  
An object representing a payer used by 1099-MISC tax documents.

**items->payroll\_income->form1099s->payer->address** (object)  
Address on the pay stub.

**items->payroll\_income->form1099s->payer->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->form1099s->payer->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->form1099s->payer->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->form1099s->payer->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->form1099s->payer->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->form1099s->payer->name** (nullable, string)  
Name of payer.

**items->payroll\_income->form1099s->payer->tin** (nullable, string)  
Tax identification number of payer.

**items->payroll\_income->form1099s->payer->telephone\_number** (nullable, string)  
Telephone number of payer.

**items->payroll\_income->form1099s->filer** (object)  
An object representing a filer used by 1099-K tax documents.

**items->payroll\_income->form1099s->filer->address** (object)  
Address on the pay stub.

**items->payroll\_income->form1099s->filer->address->city** (nullable, string)  
The full city name.

**items->payroll\_income->form1099s->filer->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**items->payroll\_income->form1099s->filer->address->postal\_code** (nullable, string)  
The postal code of the address.

**items->payroll\_income->form1099s->filer->address->region** (nullable, string)  
The region or state. Example: "NC"

**items->payroll\_income->form1099s->filer->address->street** (nullable, string)  
The full street address.

**items->payroll\_income->form1099s->filer->name** (nullable, string)  
Name of filer.

**items->payroll\_income->form1099s->filer->tin** (nullable, string)  
Tax identification number of filer.

**items->payroll\_income->form1099s->filer->type** (nullable, string)  
One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party Possible values: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party

**items->payroll\_income->form1099s->tax\_year** (nullable, string)  
Tax year of the tax form.

**items->payroll\_income->form1099s->rents** (nullable, number)  
Amount in rent by payer. Format: double

**items->payroll\_income->form1099s->royalties** (nullable, number)  
Amount in royalties by payer. Format: double

**items->payroll\_income->form1099s->other\_income** (nullable, number)  
Amount in other income by payer. Format: double

**items->payroll\_income->form1099s->federal\_income\_tax\_withheld** (nullable, number)  
Amount of federal income tax withheld from payer. Format: double

**items->payroll\_income->form1099s->fishing\_boat\_proceeds** (nullable, number)  
Amount of fishing boat proceeds from payer. Format: double

**items->payroll\_income->form1099s->medical\_and\_healthcare\_payments** (nullable, number)  
Amount of medical and healthcare payments from payer. Format: double

**items->payroll\_income->form1099s->nonemployee\_compensation** (nullable, number)  
Amount of nonemployee compensation from payer. Format: double

**items->payroll\_income->form1099s->substitute\_payments\_in\_lieu\_of\_dividends\_or\_interest** (nullable, number)  
Amount of substitute payments made by payer. Format: double

**items->payroll\_income->form1099s->payer\_made\_direct\_sales\_of\_5000\_or\_more\_of\_consumer\_products\_to\_buyer** (nullable, string)  
Whether or not payer made direct sales over $5000 of consumer products.

**items->payroll\_income->form1099s->crop\_insurance\_proceeds** (nullable, number)  
Amount of crop insurance proceeds. Format: double

**items->payroll\_income->form1099s->excess\_golden\_parachute\_payments** (nullable, number)  
Amount of golden parachute payments made by payer. Format: double

**items->payroll\_income->form1099s->gross\_proceeds\_paid\_to\_an\_attorney** (nullable, number)  
Amount of gross proceeds paid to an attorney by payer. Format: double

**items->payroll\_income->form1099s->section\_409a\_deferrals** (nullable, number)  
Amount of 409A deferrals earned by payer. Format: double

**items->payroll\_income->form1099s->section\_409a\_income** (nullable, number)  
Amount of 409A income earned by payer. Format: double

**items->payroll\_income->form1099s->state\_tax\_withheld** (nullable, number)  
Amount of state tax withheld of payer for primary state. Format: double

**items->payroll\_income->form1099s->state\_tax\_withheld\_lower** (nullable, number)  
Amount of state tax withheld of payer for secondary state. Format: double

**items->payroll\_income->form1099s->payer\_state\_number** (nullable, string)  
Primary state ID.

**items->payroll\_income->form1099s->payer\_state\_number\_lower** (nullable, string)  
Secondary state ID.

**items->payroll\_income->form1099s->state\_income** (nullable, number)  
State income reported for primary state. Format: double

**items->payroll\_income->form1099s->state\_income\_lower** (nullable, number)  
State income reported for secondary state. Format: double

**items->payroll\_income->form1099s->transactions\_reported** (nullable, string)  
One of the values will be provided Payment card Third party network Possible values: Payment card, Third party network

**items->payroll\_income->form1099s->pse\_name** (nullable, string)  
Name of the PSE (Payment Settlement Entity).

**items->payroll\_income->form1099s->pse\_telephone\_number** (nullable, string)  
Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity).

**items->payroll\_income->form1099s->gross\_amount** (nullable, number)  
Gross amount reported. Format: double

**items->payroll\_income->form1099s->card\_not\_present\_transaction** (nullable, number)  
Amount in card not present transactions. Format: double

**items->payroll\_income->form1099s->merchant\_category\_code** (nullable, string)  
Merchant category of filer.

**items->payroll\_income->form1099s->number\_of\_payment\_transactions** (nullable, string)  
Number of payment transactions made.

**items->payroll\_income->form1099s->january\_amount** (nullable, number)  
Amount reported for January. Format: double

**items->payroll\_income->form1099s->february\_amount** (nullable, number)  
Amount reported for February. Format: double

**items->payroll\_income->form1099s->march\_amount** (nullable, number)  
Amount reported for March. Format: double

**items->payroll\_income->form1099s->april\_amount** (nullable, number)  
Amount reported for April. Format: double

**items->payroll\_income->form1099s->may\_amount** (nullable, number)  
Amount reported for May. Format: double

**items->payroll\_income->form1099s->june\_amount** (nullable, number)  
Amount reported for June. Format: double

**items->payroll\_income->form1099s->july\_amount** (nullable, number)  
Amount reported for July. Format: double

**items->payroll\_income->form1099s->august\_amount** (nullable, number)  
Amount reported for August. Format: double

**items->payroll\_income->form1099s->september\_amount** (nullable, number)  
Amount reported for September. Format: double

**items->payroll\_income->form1099s->october\_amount** (nullable, number)  
Amount reported for October. Format: double

**items->payroll\_income->form1099s->november\_amount** (nullable, number)  
Amount reported for November. Format: double

**items->payroll\_income->form1099s->december\_amount** (nullable, number)  
Amount reported for December. Format: double

**items->payroll\_income->form1099s->primary\_state** (nullable, string)  
Primary state of business.

**items->payroll\_income->form1099s->secondary\_state** (nullable, string)  
Secondary state of business.

**items->payroll\_income->form1099s->primary\_state\_id** (nullable, string)  
Primary state ID.

**items->payroll\_income->form1099s->secondary\_state\_id** (nullable, string)  
Secondary state ID.

**items->payroll\_income->form1099s->primary\_state\_income\_tax** (nullable, number)  
State income tax reported for primary state. Format: double

**items->payroll\_income->form1099s->secondary\_state\_income\_tax** (nullable, number)  
State income tax reported for secondary state. Format: double

**items->status** (nullable, object)  
Details about the status of the payroll item.

**items->status->processing\_status** (nullable, string)  
Denotes the processing status for the verification. UNKNOWN: The processing status could not be determined. PROCESSING\_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved. PROCESSING: The verification is still processing. The data is not available yet. FAILED: The processing failed to complete successfully. APPROVAL\_STATUS\_PENDING: The processing has completed but the user has not yet approved the sharing of the data. Possible values: UNKNOWN, PROCESSING\_COMPLETE, PROCESSING, FAILED, APPROVAL\_STATUS\_PENDING

**items->updated\_at** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated. Format: date-time

**error** (nullable, 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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->error\_code\_reason** (nullable, 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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (nullable, 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.

**error->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.

**error->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.

**error->status** (nullable, 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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "items": [
    {
      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
      "institution_id": "ins_92",
      "institution_name": "ADP",
      "accounts": [
        {
          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
          "rate_of_pay": {
            "pay_amount": 100000,
            "pay_rate": "ANNUAL"
          },
          "pay_frequency": "BIWEEKLY"
        }
      ],
      "payroll_income": [
        {
          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
          "pay_stubs": [
            {
              "deductions": {
                "breakdown": [
                  {
                    "current_amount": 123.45,
                    "description": "taxes",
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null,
                    "ytd_amount": 246.9
                  }
                ],
                "total": {
                  "current_amount": 123.45,
                  "iso_currency_code": "USD",
                  "unofficial_currency_code": null,
                  "ytd_amount": 246.9
                }
              },
              "document_metadata": {
                "document_type": "PAYSTUB",
                "name": "paystub.pdf",
                "status": "PROCESSING_COMPLETE",
                "download_url": null
              },
              "document_id": "2jkflanbd",
              "earnings": {
                "breakdown": [
                  {
                    "canonical_description": "REGULAR_PAY",
                    "current_amount": 200.22,
                    "description": "salary earned",
                    "hours": 80,
                    "iso_currency_code": "USD",
                    "rate": null,
                    "unofficial_currency_code": null,
                    "ytd_amount": 400.44
                  },
                  {
                    "canonical_description": "BONUS",
                    "current_amount": 100,
                    "description": "bonus earned",
                    "hours": null,
                    "iso_currency_code": "USD",
                    "rate": null,
                    "unofficial_currency_code": null,
                    "ytd_amount": 100
                  }
                ],
                "total": {
                  "current_amount": 300.22,
                  "hours": 160,
                  "iso_currency_code": "USD",
                  "unofficial_currency_code": null,
                  "ytd_amount": 500.44
                }
              },
              "employee": {
                "address": {
                  "city": "SAN FRANCISCO",
                  "country": "US",
                  "postal_code": "94133",
                  "region": "CA",
                  "street": "2140 TAYLOR ST"
                },
                "name": "ANNA CHARLESTON",
                "marital_status": "SINGLE",
                "taxpayer_id": {
                  "id_type": "SSN",
                  "id_mask": "3333"
                }
              },
              "employer": {
                "name": "PLAID INC",
                "address": {
                  "city": "SAN FRANCISCO",
                  "country": "US",
                  "postal_code": "94111",
                  "region": "CA",
                  "street": "1098 HARRISON ST"
                }
              },
              "net_pay": {
                "current_amount": 123.34,
                "description": "TOTAL NET PAY",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "ytd_amount": 253.54
              },
              "pay_period_details": {
                "distribution_breakdown": [
                  {
                    "account_name": "Big time checking",
                    "bank_name": "bank of plaid",
                    "current_amount": 176.77,
                    "iso_currency_code": "USD",
                    "mask": "1223",
                    "type": "checking",
                    "unofficial_currency_code": null
                  }
                ],
                "end_date": "2020-12-15",
                "gross_earnings": 4500,
                "iso_currency_code": "USD",
                "pay_amount": 1490.21,
                "pay_date": "2020-12-15",
                "pay_frequency": "BIWEEKLY",
                "start_date": "2020-12-01",
                "unofficial_currency_code": null
              }
            }
          ],
          "w2s": [
            {
              "allocated_tips": "1000",
              "box_12": [
                {
                  "amount": "200",
                  "code": "AA"
                }
              ],
              "box_9": "box9",
              "dependent_care_benefits": "1000",
              "document_metadata": {
                "document_type": "US_TAX_W2",
                "download_url": null,
                "name": "w_2.pdf",
                "status": "PROCESSING_COMPLETE"
              },
              "document_id": "1pkflebk4",
              "employee": {
                "address": {
                  "city": "San Francisco",
                  "country": "US",
                  "postal_code": "94103",
                  "region": "CA",
                  "street": "1234 Grand St"
                },
                "name": "Josie Georgia Harrison",
                "marital_status": "SINGLE",
                "taxpayer_id": {
                  "id_type": "SSN",
                  "id_mask": "1234"
                }
              },
              "employer": {
                "address": {
                  "city": "New York",
                  "country": "US",
                  "postal_code": "10010",
                  "region": "NY",
                  "street": "456 Main St"
                },
                "name": "Acme Inc"
              },
              "employer_id_number": "12-1234567",
              "federal_income_tax_withheld": "1000",
              "medicare_tax_withheld": "1000",
              "medicare_wages_and_tips": "1000",
              "nonqualified_plans": "1000",
              "other": "other",
              "retirement_plan": "CHECKED",
              "social_security_tax_withheld": "1000",
              "social_security_tips": "1000",
              "social_security_wages": "1000",
              "state_and_local_wages": [
                {
                  "employer_state_id_number": "11111111111AAA",
                  "local_income_tax": "200",
                  "local_wages_and_tips": "200",
                  "locality_name": "local",
                  "state": "UT",
                  "state_income_tax": "200",
                  "state_wages_tips": "200"
                }
              ],
              "statutory_employee": "CHECKED",
              "tax_year": "2020",
              "third_party_sick_pay": "CHECKED",
              "wages_tips_other_comp": "1000"
            }
          ],
          "form1099s": [
            {
              "april_amount": null,
              "august_amount": null,
              "card_not_present_transaction": null,
              "crop_insurance_proceeds": 1000,
              "december_amount": null,
              "document_id": "mvMZ59Z2a5",
              "document_metadata": {
                "document_type": "US_TAX_1099_MISC",
                "download_url": null,
                "name": "form_1099_misc.pdf",
                "status": "PROCESSING_COMPLETE"
              },
              "excess_golden_parachute_payments": 1000,
              "february_amount": null,
              "federal_income_tax_withheld": 1000,
              "filer": {
                "address": {
                  "city": null,
                  "country": null,
                  "postal_code": null,
                  "region": null,
                  "street": null
                },
                "name": null,
                "tin": null,
                "type": null
              },
              "fishing_boat_proceeds": 1000,
              "form_1099_type": "FORM_1099_TYPE_MISC",
              "gross_amount": 1000,
              "gross_proceeds_paid_to_an_attorney": 1000,
              "january_amount": null,
              "july_amount": null,
              "june_amount": null,
              "march_amount": null,
              "may_amount": null,
              "medical_and_healthcare_payments": 1000,
              "merchant_category_code": null,
              "nonemployee_compensation": 1000,
              "november_amount": null,
              "number_of_payment_transactions": null,
              "october_amount": null,
              "other_income": 1000,
              "payer": {
                "address": {
                  "city": "SAN FRANCISCO",
                  "country": "US",
                  "postal_code": "94111",
                  "region": "CA",
                  "street": "1098 HARRISON ST"
                },
                "name": "PLAID INC",
                "telephone_number": "(123)456-7890",
                "tin": "12-3456789"
              },
              "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null,
              "payer_state_number": "CA 12345",
              "payer_state_number_lower": null,
              "primary_state": null,
              "primary_state_id": "CA 12345",
              "primary_state_income_tax": 1000,
              "pse_name": null,
              "pse_telephone_number": null,
              "recipient": {
                "account_number": "45678",
                "address": {
                  "city": "SAN FRANCISCO",
                  "country": "US",
                  "postal_code": "94133",
                  "region": "CA",
                  "street": "2140 TAYLOR ST"
                },
                "facta_filing_requirement": "CHECKED",
                "name": "Josie Georgia Harrison",
                "second_tin_exists": "NOT CHECKED",
                "tin": "12-3456789"
              },
              "rents": 1000,
              "royalties": 1000,
              "secondary_state": null,
              "secondary_state_id": null,
              "secondary_state_income_tax": null,
              "section_409a_deferrals": 1000,
              "section_409a_income": 1000,
              "september_amount": null,
              "state_income": 1000,
              "state_income_lower": null,
              "state_tax_withheld": 1000,
              "state_tax_withheld_lower": null,
              "substitute_payments_in_lieu_of_dividends_or_interest": null,
              "tax_year": "2022",
              "transactions_reported": null
            }
          ]
        }
      ],
      "status": {
        "processing_status": "PROCESSING_COMPLETE"
      },
      "updated_at": "2022-08-02T21:14:54Z"
    }
  ],
  "request_id": "2pxQ59buGdsHRef"
}
```

\=\*=\*=\*=

#### /credit/payroll\_income/risk\_signals/get 

#### Retrieve fraud insights for a user's manually uploaded document(s). 

[/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score.  
To trigger risk signal generation for an Item, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `parsing_config` set to include `risk_signals`, or call [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) . Once risk signal generation has been triggered, [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) can be called at any time after the `INCOME_VERIFICATION_RISK_SIGNALS` webhook has been fired.  
[/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
const request: CreditPayrollIncomeRiskSignalsGetRequest = {
  user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12',
};
try {
  const response = await client.creditPayrollIncomeRiskSignalsGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**items** (\[object\])  
Array of payroll items.

**items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**items->verification\_risk\_signals** (\[object\])  
Array of payroll income document authenticity data retrieved for each of the user's accounts.

**items->verification\_risk\_signals->account\_id** (nullable, string)  
ID of the payroll provider account.

**items->verification\_risk\_signals->single\_document\_risk\_signals** (\[object\])  
Array of document metadata and associated risk signals per document

**items->verification\_risk\_signals->single\_document\_risk\_signals->document\_reference** (object)  
Object containing metadata for the document

**items->verification\_risk\_signals->single\_document\_risk\_signals->document\_reference->document\_id** (nullable, string)  
An identifier of the document referenced by the document metadata.

**items->verification\_risk\_signals->single\_document\_risk\_signals->document\_reference->document\_name** (string)  
The name of the document

**items->verification\_risk\_signals->single\_document\_risk\_signals->document\_reference->status** (string)  
Status of a document for risk signal analysis Possible values: PROCESSING, PROCESSING\_COMPLETE, PROCESSING\_ERROR, PASSWORD\_PROTECTED, VIRUS\_DETECTED

**items->verification\_risk\_signals->single\_document\_risk\_signals->document\_reference->document\_type** (nullable, string)  
Type of a document for risk signal analysis Possible values: UNKNOWN, BANK\_STATEMENT, BENEFITS\_STATEMENT, BUSINESS\_FILING, CHECK, DRIVING\_LICENSE, FINANCIAL\_STATEMENT, INVOICE, PAYSLIP, SOCIAL\_SECURITY\_CARD, TAX\_FORM, UTILITY\_BILL

**items->verification\_risk\_signals->single\_document\_risk\_signals->document\_reference->file\_type** (nullable, string)  
The file type for risk signal analysis Possible values: UNKNOWN, IMAGE\_PDF, SCAN\_OCR, TRUE\_PDF, IMAGE, MIXED\_PAGE\_PDF, EMPTY\_PDF, FLATTENED\_PDF

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals** (\[object\])  
Array of attributes that indicate whether or not there is fraud risk with a document

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->type** (nullable, string)  
The type of risk found in the risk signal check. Possible values: FONT, MASKING, OVERLAID\_TEXT, EDITED\_TEXT, TEXT\_COMPRESSION, ADDRESS\_FORMAT\_ANOMALY, DATE\_FORMAT\_ANOMALY, FONT\_ANOMALY, NAME\_FORMAT\_ANOMALY, PDF\_ALIGNMENT, BRUSH\_DETECTION, METADATA\_DATES\_OUTSIDE\_WINDOW, METADATA\_DATES\_INSIDE\_WINDOW, METADATA\_DATES\_MISSING, METADATA\_DATES\_MATCH, ADOBE\_FONTS, ANNOTATION\_DATES, ANNOTATIONS, EDITED\_WHILE\_SCANNED, EXIF\_DATA\_MODIFIED, HIGH\_USER\_ACCESS, MALFORMED\_DATE, QPDF, TEXT\_LAYER\_TEXT, TOUCHUP\_TEXT, FLATTENED\_PDF, BLACKLISTS, COPYCAT\_IMAGE, COPYCAT\_TEXT, REJECTED\_CUSTOMER, TEMPLATES, SOFTWARE\_BLACKLIST

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->field** (nullable, string)  
The field which the risk signal was computed for

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->has\_fraud\_risk** (nullable, boolean)  
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->institution\_metadata** (nullable, object)  
An object which contains additional metadata about the institution used to compute the verification attribute

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->institution\_metadata->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->expected\_value** (nullable, string)  
The expected value of the field, as seen on the document

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->actual\_value** (nullable, string)  
The derived value obtained in the risk signal calculation process for this field

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->signal\_description** (nullable, string)  
A human-readable explanation providing more detail into the particular risk signal

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_signals->page\_number** (nullable, integer)  
The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0.

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_summary** (object)  
A summary across all risk signals associated with a document

**items->verification\_risk\_signals->single\_document\_risk\_signals->risk\_summary->risk\_score** (nullable, number)  
A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent. You can automatically reject documents with a high risk score, automatically accept documents with a low risk score, and manually review documents in between. We suggest starting with a threshold of 80 for auto-rejection and 20 for auto-acceptance. As you gather more data points on typical risk scores for your use case, you can tune these parameters to reduce the number of documents undergoing manual review.

**items->verification\_risk\_signals->multi\_document\_risk\_signals** (\[object\])  
Array of risk signals computed from a set of uploaded documents and the associated documents' metadata

**items->verification\_risk\_signals->multi\_document\_risk\_signals->document\_references** (\[object\])  
Array of objects containing attributes that could indicate if a document is fraudulent

**items->verification\_risk\_signals->multi\_document\_risk\_signals->document\_references->document\_id** (nullable, string)  
An identifier of the document referenced by the document metadata.

**items->verification\_risk\_signals->multi\_document\_risk\_signals->document\_references->document\_name** (string)  
The name of the document

**items->verification\_risk\_signals->multi\_document\_risk\_signals->document\_references->status** (string)  
Status of a document for risk signal analysis Possible values: PROCESSING, PROCESSING\_COMPLETE, PROCESSING\_ERROR, PASSWORD\_PROTECTED, VIRUS\_DETECTED

**items->verification\_risk\_signals->multi\_document\_risk\_signals->document\_references->document\_type** (nullable, string)  
Type of a document for risk signal analysis Possible values: UNKNOWN, BANK\_STATEMENT, BENEFITS\_STATEMENT, BUSINESS\_FILING, CHECK, DRIVING\_LICENSE, FINANCIAL\_STATEMENT, INVOICE, PAYSLIP, SOCIAL\_SECURITY\_CARD, TAX\_FORM, UTILITY\_BILL

**items->verification\_risk\_signals->multi\_document\_risk\_signals->document\_references->file\_type** (nullable, string)  
The file type for risk signal analysis Possible values: UNKNOWN, IMAGE\_PDF, SCAN\_OCR, TRUE\_PDF, IMAGE, MIXED\_PAGE\_PDF, EMPTY\_PDF, FLATTENED\_PDF

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals** (\[object\])  
Array of attributes that indicate whether or not there is fraud risk with a set of documents

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->type** (nullable, string)  
The type of risk found in the risk signal check. Possible values: FONT, MASKING, OVERLAID\_TEXT, EDITED\_TEXT, TEXT\_COMPRESSION, ADDRESS\_FORMAT\_ANOMALY, DATE\_FORMAT\_ANOMALY, FONT\_ANOMALY, NAME\_FORMAT\_ANOMALY, PDF\_ALIGNMENT, BRUSH\_DETECTION, METADATA\_DATES\_OUTSIDE\_WINDOW, METADATA\_DATES\_INSIDE\_WINDOW, METADATA\_DATES\_MISSING, METADATA\_DATES\_MATCH, ADOBE\_FONTS, ANNOTATION\_DATES, ANNOTATIONS, EDITED\_WHILE\_SCANNED, EXIF\_DATA\_MODIFIED, HIGH\_USER\_ACCESS, MALFORMED\_DATE, QPDF, TEXT\_LAYER\_TEXT, TOUCHUP\_TEXT, FLATTENED\_PDF, BLACKLISTS, COPYCAT\_IMAGE, COPYCAT\_TEXT, REJECTED\_CUSTOMER, TEMPLATES, SOFTWARE\_BLACKLIST

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->field** (nullable, string)  
The field which the risk signal was computed for

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->has\_fraud\_risk** (nullable, boolean)  
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->institution\_metadata** (nullable, object)  
An object which contains additional metadata about the institution used to compute the verification attribute

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->institution\_metadata->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->expected\_value** (nullable, string)  
The expected value of the field, as seen on the document

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->actual\_value** (nullable, string)  
The derived value obtained in the risk signal calculation process for this field

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->signal\_description** (nullable, string)  
A human-readable explanation providing more detail into the particular risk signal

**items->verification\_risk\_signals->multi\_document\_risk\_signals->risk\_signals->page\_number** (nullable, integer)  
The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0.

**error** (nullable, 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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->error\_code\_reason** (nullable, 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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (nullable, 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.

**error->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.

**error->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.

**error->status** (nullable, 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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "items": [
    {
      "item_id": "testItemID",
      "verification_risk_signals": [
        {
          "account_id": null,
          "multi_document_risk_signals": [],
          "single_document_risk_signals": [
            {
              "document_reference": {
                "document_id": "lRepoQjxlJ1nz",
                "document_name": "Paystub.pdf",
                "file_type": "TRUE_PDF"
              },
              "risk_summary": {
                "risk_score": 70
              },
              "risk_signals": [
                {
                  "actual_value": "0.00",
                  "expected_value": "25.09",
                  "field": null,
                  "signal_description": null,
                  "has_fraud_risk": true,
                  "type": "MASKING",
                  "page_number": 1,
                  "institution_metadata": {
                    "item_id": "testItemID"
                  }
                },
                {
                  "actual_value": null,
                  "expected_value": null,
                  "field": null,
                  "signal_description": "Creation date and modification date do not match",
                  "has_fraud_risk": true,
                  "institution_metadata": null,
                  "type": "METADATA_DATES_OUTSIDE_WINDOW",
                  "page_number": 0
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "request_id": "LhQf0THi8SH1yJm"
}
```

\=\*=\*=\*=

#### /credit/employment/get 

#### Retrieve a summary of an individual's employment information 

[/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) returns a list of items with employment information from a user's payroll provider that was verified by an end user.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

```javascript
const request: CreditEmploymentGetRequest = {
  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
};


try {
  const response = await client.creditEmploymentGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**items** (\[object\])  
Array of employment items.

**items->item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

nullable, string

**items->employments** (\[object\])  
ID of the payroll provider account.

**items->employments->status** (nullable, string)  
Current employment status. Possible values: ACTIVE, INACTIVE, null

**items->employments->start\_date** (nullable, string)  
Start of employment in ISO 8601 format (YYYY-MM-DD). Format: date

**items->employments->end\_date** (nullable, string)  
End of employment, if applicable. Provided in ISO 8601 format (YYY-MM-DD). Format: date

**items->employments->employer** (object)  
An object containing employer data.

**items->employments->employer->name** (nullable, string)  
Name of employer.

**items->employments->title** (nullable, string)  
Current title of employee.

**items->employments->platform\_ids** (object)  
The object containing a set of ids related to an employee.

**items->employments->platform\_ids->employee\_id** (nullable, string)  
The ID of an employee as given by their employer.

**items->employments->platform\_ids->payroll\_id** (nullable, string)  
The ID of an employee as given by their payroll.

**items->employments->platform\_ids->position\_id** (nullable, string)  
The ID of the position of the employee.

**items->employments->employee\_type** (nullable, string)  
The type of employment for the individual. "FULL\_TIME": A full-time employee. "PART\_TIME": A part-time employee. "CONTRACTOR": An employee typically hired externally through a contracting group. "TEMPORARY": A temporary employee. "OTHER": The employee type is not one of the above defined types. Possible values: FULL\_TIME, PART\_TIME, CONTRACTOR, TEMPORARY, OTHER, null

**items->employments->last\_paystub\_date** (nullable, string)  
The date of the employee's most recent paystub in ISO 8601 format (YYYY-MM-DD). Format: date

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "items": [
    {
      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
      "employments": [
        {
          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
          "status": "ACTIVE",
          "start_date": "2020-01-01",
          "end_date": null,
          "employer": {
            "name": "Plaid Inc"
          },
          "title": "Software Engineer",
          "platform_ids": {
            "employee_id": "1234567",
            "position_id": "8888",
            "payroll_id": "1234567"
          },
          "employee_type": "FULL_TIME",
          "last_paystub_date": "2022-01-15"
        }
      ]
    }
  ],
  "request_id": "LhQf0THi8SH1yJm"
}
```

\=\*=\*=\*=

#### /credit/payroll\_income/parsing\_config/update 

#### Update the parsing configuration for a document income verification 

[/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) updates the parsing configuration for a document income verification.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**parsing\_config** (required, \[string\])  
The types of analysis to enable for the document income verification session Possible values: ocr, risk\_signals

```javascript
const request: CreditPayrollIncomeParsingConfigUpdateRequest = {
  user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12',
  parsing_config: ['fraud_risk'],
};
try {
  const response = await client.creditPayrollIncomeParsingConfigUpdate(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "LhQf0THi8SH1yJm"
}
```

\=\*=\*=\*=

#### /credit/payroll\_income/refresh 

#### Refresh a digital payroll income verification 

[/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) refreshes a given digital payroll income verification.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**options** (object)  
An optional object for /credit/payroll\_income/refresh request options.

**options->item\_ids** (\[string\])  
An array of item\_ids to be refreshed. Each item\_id should uniquely identify a payroll income item. If this field is not provided, all item\_ids associated with the user\_token will be refreshed.

**options->webhook** (string)  
The URL where Plaid will send the payroll income refresh webhook.

```javascript
const request: PayrollIncomeRefreshRequest = {
  client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d',
};


try {
  const response = await client.userCreate(request);
} catch (error) {
  // handle error
}
```

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

**verification\_refresh\_status** (string)  
The verification refresh status. One of the following: "USER\_PRESENCE\_REQUIRED" User presence is required to refresh an income verification. "SUCCESSFUL" The income verification refresh was successful. "NOT\_FOUND" No new data was found after the income verification refresh. Possible values: USER\_PRESENCE\_REQUIRED, SUCCESSFUL, NOT\_FOUND

```json
{
  "request_id": "nTkbCH41HYmpbm5",
  "verification_refresh_status": "USER_PRESENCE_REQUIRED"
}
```

### Webhooks 

Income webhooks are sent to indicate when an income verification or document fraud risk evaluation has finished processing.

\=\*=\*=\*=

#### INCOME\_VERIFICATION 

Fired when the status of an income verification instance has changed. This webhook is fired for both the Document and Payroll Income flows, but not the Bank Income flow. It will typically take several minutes for this webhook to fire after the end user has uploaded their documents in the Document Income flow.

#### Properties 

**webhook\_type** (string)  
"INCOME"

**webhook\_code** (string)  
INCOME\_VERIFICATION

**item\_id** (string)  
The Item ID associated with the verification.

**user\_id** (string)  
The Plaid user\_id of the User associated with this webhook, warning, or error.

**verification\_status** (string)  
VERIFICATION\_STATUS\_PROCESSING\_COMPLETE: The income verification processing has completed. This indicates that the documents have been parsed successfully or that the documents were not parsable. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /credit/payroll\_income/get endpoint and check the document metadata to see which documents were successfully parsed. VERIFICATION\_STATUS\_PROCESSING\_FAILED: An unexpected internal error occurred when attempting to process the verification documentation. VERIFICATION\_STATUS\_PENDING\_APPROVAL: (deprecated) The income verification has been sent to the user for review.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "INCOME",
  "webhook_code": "INCOME_VERIFICATION",
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE",
  "environment": "production"
}
```

\=\*=\*=\*=

#### INCOME\_VERIFICATION\_RISK\_SIGNALS 

Fired when risk signals have been processed for documents uploaded via Document Income. It will typically take a minute or two for this webhook to fire after the end user has uploaded their documents in the Document Income flow. Once this webhook has fired, [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) may then be called to determine whether the documents were successfully processed and to retrieve risk data.

#### Properties 

**webhook\_type** (string)  
"INCOME"

**webhook\_code** (string)  
INCOME\_VERIFICATION\_RISK\_SIGNALS

**item\_id** (string)  
The Item ID associated with the verification.

**user\_id** (string)  
The Plaid user\_id of the User associated with this webhook, warning, or error.

**risk\_signals\_status** (string)  
RISK\_SIGNALS\_PROCESSING\_COMPLETE: The income verification fraud detection processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /credit/payroll\_income/risk\_signals/get endpoint to get all risk signal data.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "INCOME",
  "webhook_code": "INCOME_VERIFICATION_RISK_SIGNALS",
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
  "status": "RISK_SIGNALS_PROCESSING_COMPLETE",
  "environment": "production"
}
```

\=\*=\*=\*=

#### BANK\_INCOME\_REFRESH\_COMPLETE 

Fired when a refreshed bank income report has finished generating or failed to generate, triggered by calling [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) . To get this webhook, subscribe via the [Dashboard](https://dashboard.plaid.com/developers/webhooks) .

#### Properties 

**webhook\_type** (string)  
INCOME

**webhook\_code** (string)  
BANK\_INCOME\_REFRESH\_COMPLETE

**user\_id** (string)  
The user\_id corresponding to the user the webhook has fired for.

**result** (string)  
The result of the bank income refresh report generation SUCCESS: The refreshed report was successfully generated and can be retrieved via /credit/bank\_income/get. FAILURE: The refreshed report failed to be generated Possible values: SUCCESS, FAILURE

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "INCOME",
  "webhook_code": "BANK_INCOME_REFRESH_COMPLETE",
  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "result": "SUCCESS",
  "environment": "production"
}
```

\=\*=\*=\*=

#### INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED 

Fired when the attempt to refresh Payroll Income data for a user via [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) failed because the user must re-connect their payroll account.

#### Properties 

**webhook\_type** (string)  
INCOME

**webhook\_code** (string)  
INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED

**user\_id** (string)  
The user\_id corresponding to the user the webhook has fired for.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "INCOME",
  "webhook_code": "INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED",
  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "environment": "production"
}
```

---


# API - Investments Move | Plaid Docs

Investments Move 
=================

#### API reference for Investments Move endpoints and webhooks 

For how-to guidance, see the [Investments Move documentation](https://plaid.com/docs/investments-move/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) | Fetch investments data required for ACATS or ATON transfer |

\=\*=\*=\*=

#### /investments/auth/get 

#### Get data needed to authorize an investments transfer 

The [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) endpoint allows developers to receive user-authorized data to facilitate the transfer of holdings

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /investments/auth/get results.

**options->account\_ids** (\[string\])  
An array of account\_ids to retrieve for the Item. An error will be returned if a provided account\_id is not associated with the Item.

```javascript
const request: InvestmentsAuthGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.investmentsAuthGet(request);
  const investmentsAuthData = response.data;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
The accounts for which data is being retrieved

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**holdings** (\[object\])  
The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the securities field.

**holdings->account\_id** (string)  
The Plaid account\_id associated with the holding.

**holdings->security\_id** (string)  
The Plaid security\_id associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The security\_id for the same security will typically be the same across different institutions, but this is not guaranteed. The security\_id does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**holdings->institution\_price** (number)  
The last price given by the institution for this security. Format: double

**holdings->institution\_price\_as\_of** (nullable, string)  
The date at which institution\_price was current. Format: date

**holdings->institution\_price\_datetime** (nullable, string)  
Date and time at which institution\_price was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). Format: date-time

**holdings->institution\_value** (number)  
The value of the holding, as reported by the institution. Format: double

**holdings->cost\_basis** (nullable, number)  
The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding). Format: double

**holdings->quantity** (number)  
The total quantity of the asset held, as reported by the financial institution. If the security is an option, quantity will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: double

**holdings->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the holding. Always null if unofficial\_currency\_code is non-null.

**holdings->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**holdings->vested\_quantity** (nullable, number)  
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities. Format: double

**holdings->vested\_value** (nullable, number)  
The value of the vested holdings as reported by the institution. Format: double

**securities** (\[object\])  
Objects describing the securities held in the accounts associated with the Item.

**securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**securities->isin** (nullable, string)  
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->cusip** (nullable, string)  
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->sedol** (deprecated, nullable, string)  
(Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK.

**securities->institution\_security\_id** (nullable, string)  
An identifier given to the security by the institution

**securities->institution\_id** (nullable, string)  
If institution\_security\_id is present, this field indicates the Plaid institution\_id of the institution to whom the identifier belongs.

**securities->proxy\_security\_id** (nullable, string)  
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.

**securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**securities->is\_cash\_equivalent** (nullable, boolean)  
Indicates that a security is a highly liquid asset and can be treated like cash.

**securities->type** (nullable, string)  
The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**securities->subtype** (nullable, string)  
The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: Possible values: asset backed security, bill, bond, bond with warrants, cash, cash management bill, common stock, convertible bond, convertible equity, cryptocurrency, depositary receipt, depositary receipt on debt, etf, float rating note, fund of funds, hedge fund, limited partnership unit, medium term note, money market debt, mortgage backed security, municipal bond, mutual fund, note, option, other, preferred convertible, preferred equity, private equity fund, real estate investment trust, structured equity product, treasury inflation protected securities, unit, warrant.

**securities->close\_price** (nullable, number)  
Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update\_datetime with the time when the price was last updated. Format: double

**securities->close\_price\_as\_of** (nullable, string)  
Date for which close\_price is accurate. Always null if close\_price is null. Format: date

**securities->update\_datetime** (nullable, string)  
Date and time at which close\_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close\_price is null. Format: date-time

**securities->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the price given. Always null if unofficial\_currency\_code is non-null.

**securities->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the security. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**securities->market\_identifier\_code** (nullable, string)  
The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded.

**securities->sector** (nullable, string)  
The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->industry** (nullable, string)  
The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->option\_contract** (nullable, object)  
Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a custom Sandbox user and the ticker field of the custom security follows the OCC Option Symbol standard with no spaces. For an example of simulating this in Sandbox, see the custom Sandbox GitHub.

**securities->option\_contract->contract\_type** (string)  
The type of this option contract. It is one of: put: for Put option contracts call: for Call option contracts

**securities->option\_contract->expiration\_date** (string)  
The expiration date for this option contract, in ISO 8601 format. Format: date

**securities->option\_contract->strike\_price** (number)  
The strike price for this option contract, per share of security. Format: double

**securities->option\_contract->underlying\_security\_ticker** (string)  
The ticker of the underlying security for this option contract.

**securities->fixed\_income** (nullable, object)  
Details about the fixed income security.

**securities->fixed\_income->yield\_rate** (nullable, object)  
Details about a fixed income security's expected rate of return.

**securities->fixed\_income->yield\_rate->percentage** (number)  
The fixed income security's expected rate of return. Format: double

**securities->fixed\_income->yield\_rate->type** (nullable, string)  
The type of rate which indicates how the predicted yield was calculated. It is one of: coupon: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. coupon\_equivalent: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. discount: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. yield: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: coupon, coupon\_equivalent, discount, yield, null

**securities->fixed\_income->maturity\_date** (nullable, string)  
The maturity date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->issue\_date** (nullable, string)  
The issue date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->face\_value** (nullable, number)  
The face value that is paid upon maturity of the fixed income security, per unit of security. Format: double

**owners** (\[object\])  
Information about the account owners for the accounts associated with the Item.

**owners->account\_id** (string)  
The ID of the account that this identity information pertains to

**owners->names** (\[string\])  
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.

**numbers** (object)  
Identifying information for transferring holdings to an investments account.

string

**numbers->acats** (\[object\])  
The Plaid account ID associated with the account numbers

**numbers->acats->account** (string)  
The full account number for the account

**numbers->acats->dtc\_numbers** (\[string\])  
Identifiers for the clearinghouses that are associated with the account in order of relevance. If this array is empty, call /institutions/get\_by\_id with the item.institution\_id to get the DTC number.

string

**numbers->aton** (\[object\])  
The Plaid account ID associated with the account numbers

**numbers->aton->account** (string)  
The full account number for the account

string

**numbers->retirement\_401k** (\[object\])  
The Plaid account ID associated with the account numbers

**numbers->retirement\_401k->plan** (string)  
The plan number for the employer's 401k retirement plan

**numbers->retirement\_401k->account** (string)  
The full account number for the account

**data\_sources** (object)  
Object with metadata pertaining to the source of data for the account numbers, owners, and holdings that are returned.

**data\_sources->numbers** (string)  
A description of the source of data for a given product/data type. INSTITUTION: The institution supports this product, and the data was provided by the institution. INSTITUTION\_MASK: The user manually provided the full account number, which was matched to the account mask provided by the institution. Only applicable to the numbers data type. USER: The institution does not support this product, and the data was manually provided by the user. Possible values: INSTITUTION, INSTITUTION\_MASK, USER

**data\_sources->owners** (string)  
A description of the source of data for a given product/data type. INSTITUTION: The institution supports this product, and the data was provided by the institution. INSTITUTION\_MASK: The user manually provided the full account number, which was matched to the account mask provided by the institution. Only applicable to the numbers data type. USER: The institution does not support this product, and the data was manually provided by the user. Possible values: INSTITUTION, INSTITUTION\_MASK, USER

**data\_sources->holdings** (string)  
A description of the source of data for a given product/data type. INSTITUTION: The institution supports this product, and the data was provided by the institution. INSTITUTION\_MASK: The user manually provided the full account number, which was matched to the account mask provided by the institution. Only applicable to the numbers data type. USER: The institution does not support this product, and the data was manually provided by the user. Possible values: INSTITUTION, INSTITUTION\_MASK, USER

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ",
      "balances": {
        "available": 43200,
        "current": 43200,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "4444",
      "name": "Plaid Money Market",
      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
      "subtype": "money market",
      "type": "depository"
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "balances": {
        "available": null,
        "current": 415.57,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    }
  ],
  "holdings": [
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": "2021-05-25",
      "institution_price_datetime": null,
      "institution_value": 0.01,
      "iso_currency_code": "USD",
      "quantity": 0.01,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null,
      "vested_quantity": 1,
      "vested_value": 1
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 0.01,
      "institution_price": 0.011,
      "institution_price_as_of": "2021-05-25",
      "institution_price_datetime": null,
      "institution_value": 110,
      "iso_currency_code": "USD",
      "quantity": 10000,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "unofficial_currency_code": null,
      "vested_quantity": null,
      "vested_value": null
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 94.808,
      "institution_price": 94.808,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 94.808,
      "iso_currency_code": "USD",
      "quantity": 1,
      "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea",
      "unofficial_currency_code": null
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 40,
      "institution_price": 42.15,
      "institution_price_as_of": "2021-05-25",
      "institution_price_datetime": null,
      "institution_value": 210.75,
      "iso_currency_code": "USD",
      "quantity": 5,
      "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",
      "unofficial_currency_code": null,
      "vested_quantity": 7,
      "vested_value": 66
    }
  ],
  "item": {
    "available_products": [
      "assets",
      "balance",
      "beacon",
      "cra_base_report",
      "cra_income_insights",
      "signal",
      "identity",
      "identity_match",
      "income",
      "income_verification",
      "investments",
      "processor_identity",
      "recurring_transactions",
      "transactions"
    ],
    "billed_products": [
      "investments_auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_115616",
    "institution_name": "Vanguard",
    "item_id": "7qBnDwLP3aIZkD7NKZ5ysk5X9xVxDWHg65oD5",
    "products": [
      "investments_auth"
    ],
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "numbers": {
    "acats": [
      {
        "account": "TR5555",
        "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
        "dtc_numbers": [
          "1111",
          "2222",
          "3333"
        ]
      }
    ]
  },
  "owners": [
    {
      "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ",
      "names": [
        "Alberta Bobbeth Charleson"
      ]
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "names": [
        "Alberta Bobbeth Charleson"
      ]
    }
  ],
  "request_id": "hPCXou4mm9Qwzzu",
  "securities": [
    {
      "close_price": 0.011,
      "close_price_as_of": null,
      "cusip": null,
      "industry": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "Nflx Feb 01'18 $355 Call",
      "option_contract": null,
      "fixed_income": null,
      "proxy_security_id": null,
      "sector": null,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "sedol": null,
      "ticker_symbol": "NFLX180201C00355000",
      "type": "derivative",
      "subtype": "option",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 94.808,
      "close_price_as_of": "2023-11-02",
      "cusip": "912797HE0",
      "fixed_income": {
        "face_value": 100,
        "issue_date": "2023-11-02",
        "maturity_date": "2024-10-31",
        "yield_rate": {
          "percentage": 5.43,
          "type": "coupon_equivalent"
        }
      },
      "industry": "Sovereign Government",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "US Treasury Bill - 5.43% 31/10/2024 USD 100",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": "Government",
      "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea",
      "sedol": null,
      "ticker_symbol": null,
      "type": "fixed income",
      "subtype": "bill",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 9.08,
      "close_price_as_of": "2024-09-09",
      "cusip": null,
      "fixed_income": null,
      "industry": "Investment Trusts or Mutual Funds",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "DoubleLine Total Return Bond I",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": "Miscellaneous",
      "security_id": "AE5rBXra1AuZLE34rkvvIyG8918m3wtRzElnJ",
      "sedol": null,
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "subtype": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 42.15,
      "close_price_as_of": null,
      "cusip": null,
      "fixed_income": null,
      "industry": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "iShares Inc MSCI Brazil",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": null,
      "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",
      "sedol": null,
      "ticker_symbol": "EWZ",
      "type": "etf",
      "subtype": "etf",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 1,
      "close_price_as_of": null,
      "cusip": null,
      "fixed_income": null,
      "industry": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": true,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "U S Dollar",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": null,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "sedol": null,
      "ticker_symbol": null,
      "type": "cash",
      "subtype": "cash",
      "unofficial_currency_code": null,
      "update_datetime": null
    }
  ],
  "data_sources": {
    "numbers": "INSTITUTION",
    "owners": "INSTITUTION",
    "holdings": "INSTITUTION"
  }
}
```

---


# API - Investments | Plaid Docs

Investments 
============

#### API reference for Investments endpoints and webhooks 

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

| Endpoints |  |
| --- | --- |
| [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) | Fetch investment holdings |
| [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) | Fetch investment transactions |
| [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) | Refresh investment transactions |

| See also |  |
| --- | --- |
| [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) | Fetch Investments Holdings data |
| [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) | Fetch Investments Transactions data |

| Webhooks |  |
| --- | --- |
| [HOLDINGS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#holdings-default_update) | New holdings available |
| [INVESTMENTS\_TRANSACTIONS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-default_update) | New transactions available |
| [INVESTMENTS\_TRANSACTIONS: HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-historical_update) | Investments data ready |

### Endpoints 

\=\*=\*=\*=

#### /investments/holdings/get 

#### Get Investment holdings 

The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) endpoint allows developers to receive user-authorized stock position data for `investment`\-type accounts.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /investments/holdings/get results. If provided, must not be null.

**options->account\_ids** (\[string\])  
An array of account\_ids to retrieve for the Item. An error will be returned if a provided account\_id is not associated with the Item.

```javascript
// Pull Holdings for an Item
const request: InvestmentsHoldingsGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.investmentsHoldingsGet(request);
  const holdings = response.data.holdings;
  const securities = response.data.securities;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
The accounts associated with the Item

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**holdings** (\[object\])  
The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the securities field.

**holdings->account\_id** (string)  
The Plaid account\_id associated with the holding.

**holdings->security\_id** (string)  
The Plaid security\_id associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The security\_id for the same security will typically be the same across different institutions, but this is not guaranteed. The security\_id does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**holdings->institution\_price** (number)  
The last price given by the institution for this security. Format: double

**holdings->institution\_price\_as\_of** (nullable, string)  
The date at which institution\_price was current. Format: date

**holdings->institution\_price\_datetime** (nullable, string)  
Date and time at which institution\_price was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). Format: date-time

**holdings->institution\_value** (number)  
The value of the holding, as reported by the institution. Format: double

**holdings->cost\_basis** (nullable, number)  
The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding). Format: double

**holdings->quantity** (number)  
The total quantity of the asset held, as reported by the financial institution. If the security is an option, quantity will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: double

**holdings->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the holding. Always null if unofficial\_currency\_code is non-null.

**holdings->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**holdings->vested\_quantity** (nullable, number)  
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities. Format: double

**holdings->vested\_value** (nullable, number)  
The value of the vested holdings as reported by the institution. Format: double

**securities** (\[object\])  
Objects describing the securities held in the accounts associated with the Item.

**securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**securities->isin** (nullable, string)  
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->cusip** (nullable, string)  
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->sedol** (deprecated, nullable, string)  
(Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK.

**securities->institution\_security\_id** (nullable, string)  
An identifier given to the security by the institution

**securities->institution\_id** (nullable, string)  
If institution\_security\_id is present, this field indicates the Plaid institution\_id of the institution to whom the identifier belongs.

**securities->proxy\_security\_id** (nullable, string)  
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.

**securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**securities->is\_cash\_equivalent** (nullable, boolean)  
Indicates that a security is a highly liquid asset and can be treated like cash.

**securities->type** (nullable, string)  
The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**securities->subtype** (nullable, string)  
The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: Possible values: asset backed security, bill, bond, bond with warrants, cash, cash management bill, common stock, convertible bond, convertible equity, cryptocurrency, depositary receipt, depositary receipt on debt, etf, float rating note, fund of funds, hedge fund, limited partnership unit, medium term note, money market debt, mortgage backed security, municipal bond, mutual fund, note, option, other, preferred convertible, preferred equity, private equity fund, real estate investment trust, structured equity product, treasury inflation protected securities, unit, warrant.

**securities->close\_price** (nullable, number)  
Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update\_datetime with the time when the price was last updated. Format: double

**securities->close\_price\_as\_of** (nullable, string)  
Date for which close\_price is accurate. Always null if close\_price is null. Format: date

**securities->update\_datetime** (nullable, string)  
Date and time at which close\_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close\_price is null. Format: date-time

**securities->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the price given. Always null if unofficial\_currency\_code is non-null.

**securities->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the security. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**securities->market\_identifier\_code** (nullable, string)  
The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded.

**securities->sector** (nullable, string)  
The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->industry** (nullable, string)  
The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->option\_contract** (nullable, object)  
Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a custom Sandbox user and the ticker field of the custom security follows the OCC Option Symbol standard with no spaces. For an example of simulating this in Sandbox, see the custom Sandbox GitHub.

**securities->option\_contract->contract\_type** (string)  
The type of this option contract. It is one of: put: for Put option contracts call: for Call option contracts

**securities->option\_contract->expiration\_date** (string)  
The expiration date for this option contract, in ISO 8601 format. Format: date

**securities->option\_contract->strike\_price** (number)  
The strike price for this option contract, per share of security. Format: double

**securities->option\_contract->underlying\_security\_ticker** (string)  
The ticker of the underlying security for this option contract.

**securities->fixed\_income** (nullable, object)  
Details about the fixed income security.

**securities->fixed\_income->yield\_rate** (nullable, object)  
Details about a fixed income security's expected rate of return.

**securities->fixed\_income->yield\_rate->percentage** (number)  
The fixed income security's expected rate of return. Format: double

**securities->fixed\_income->yield\_rate->type** (nullable, string)  
The type of rate which indicates how the predicted yield was calculated. It is one of: coupon: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. coupon\_equivalent: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. discount: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. yield: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: coupon, coupon\_equivalent, discount, yield, null

**securities->fixed\_income->maturity\_date** (nullable, string)  
The maturity date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->issue\_date** (nullable, string)  
The issue date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->face\_value** (nullable, number)  
The face value that is paid upon maturity of the fixed income security, per unit of security. Format: double

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**is\_investments\_fallback\_item** (boolean)  
When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow.

```json
{
  "accounts": [
    {
      "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",
      "balances": {
        "available": 43200,
        "current": 43200,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "4444",
      "name": "Plaid Money Market",
      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
      "subtype": "money market",
      "type": "depository"
    },
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "balances": {
        "available": null,
        "current": 110.01,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "balances": {
        "available": null,
        "current": 24580.0605,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    },
    {
      "account_id": "ax0xgOBYRAIqOOjeLZr0iZBb8r6K88HZXpvmq",
      "balances": {
        "available": 48200.03,
        "current": 48200.03,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "4092",
      "name": "Plaid Crypto Exchange Account",
      "official_name": null,
      "subtype": "crypto exchange",
      "type": "investment"
    }
  ],
  "holdings": [
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 0.01,
      "iso_currency_code": "USD",
      "quantity": 0.01,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 1.5,
      "institution_price": 2.11,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 2.11,
      "iso_currency_code": "USD",
      "quantity": 1,
      "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 10,
      "institution_price": 10.42,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 20.84,
      "iso_currency_code": "USD",
      "quantity": 2,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "unofficial_currency_code": null
    },
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 0.01,
      "institution_price": 0.011,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 110,
      "iso_currency_code": "USD",
      "quantity": 10000,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 23,
      "institution_price": 27,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 636.309,
      "iso_currency_code": "USD",
      "quantity": 23.567,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 15,
      "institution_price": 13.73,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 1373.6865,
      "iso_currency_code": "USD",
      "quantity": 100.05,
      "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 948.08,
      "institution_price": 94.808,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 948.08,
      "iso_currency_code": "USD",
      "quantity": 10,
      "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": "2021-04-13",
      "institution_price_datetime": null,
      "institution_value": 12345.67,
      "iso_currency_code": "USD",
      "quantity": 12345.67,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null
    },
    {
      "account_id": "ax0xgOBYRAIqOOjeLZr0iZBb8r6K88HZXpvmq",
      "cost_basis": 92.47,
      "institution_price": 0.177494362,
      "institution_price_as_of": "2022-01-14",
      "institution_price_datetime": "2022-06-07T23:01:00Z",
      "institution_value": 4437.35905,
      "iso_currency_code": "USD",
      "quantity": 25000,
      "security_id": "vLRMV3MvY1FYNP91on35CJD5QN5rw9Fpa9qOL",
      "unofficial_currency_code": null
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "identity",
      "liabilities",
      "transactions"
    ],
    "billed_products": [
      "assets",
      "auth",
      "investments"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "institution_name": "Chase",
    "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "request_id": "l68wb8zpS0hqmsJ",
  "securities": [
    {
      "close_price": 0.011,
      "close_price_as_of": "2021-04-13",
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "Nflx Feb 01'18 $355 Call",
      "proxy_security_id": null,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "sedol": null,
      "ticker_symbol": "NFLX180201C00355000",
      "type": "derivative",
      "subtype": "option",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Technology Services",
      "industry": "Internet Software or Services",
      "option_contract": {
        "contract_type": "call",
        "expiration_date": "2018-02-01",
        "strike_price": 355,
        "underlying_security_ticker": "NFLX"
      },
      "fixed_income": null
    },
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "subtype": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Miscellaneous",
      "industry": "Investment Trusts or Mutual Funds",
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 2.11,
      "close_price_as_of": null,
      "cusip": "00448Q201",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US00448Q2012",
      "iso_currency_code": "USD",
      "name": "Achillion Pharmaceuticals Inc.",
      "proxy_security_id": null,
      "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
      "sedol": null,
      "ticker_symbol": "ACHN",
      "type": "equity",
      "subtype": "common stock",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Health Technology",
      "industry": "Major Pharmaceuticals",
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 10.42,
      "close_price_as_of": null,
      "cusip": "258620103",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US2586201038",
      "iso_currency_code": "USD",
      "name": "DoubleLine Total Return Bond Fund",
      "proxy_security_id": null,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "sedol": null,
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "subtype": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": null,
      "industry": null,
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 1,
      "close_price_as_of": null,
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": true,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "U S Dollar",
      "proxy_security_id": null,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "sedol": null,
      "ticker_symbol": "USD",
      "type": "cash",
      "subtype": "cash",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": null,
      "sector": null,
      "industry": null,
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 13.73,
      "close_price_as_of": null,
      "cusip": null,
      "institution_id": "ins_3",
      "institution_security_id": "NHX105509",
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "NH PORTFOLIO 1055 (FIDELITY INDEX)",
      "proxy_security_id": null,
      "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
      "sedol": null,
      "ticker_symbol": "NHX105509",
      "type": "etf",
      "subtype": "etf",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": null,
      "industry": null,
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 94.808,
      "close_price_as_of": "2023-11-02",
      "cusip": "912797HE0",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "US Treasury Bill - 5.43% 31/10/2024 USD 100",
      "proxy_security_id": null,
      "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea",
      "sedol": null,
      "ticker_symbol": null,
      "type": "fixed income",
      "subtype": "bill",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": null,
      "sector": "Government",
      "industry": "Sovereign Government",
      "option_contract": null,
      "fixed_income": {
        "face_value": 100,
        "issue_date": "2023-11-02",
        "maturity_date": "2024-10-31",
        "yield_rate": {
          "percentage": 5.43,
          "type": "coupon_equivalent"
        }
      }
    },
    {
      "close_price": 0.140034616,
      "close_price_as_of": "2022-01-24",
      "cusip": null,
      "institution_id": "ins_3",
      "institution_security_id": null,
      "is_cash_equivalent": true,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "Dogecoin",
      "proxy_security_id": null,
      "security_id": "vLRMV3MvY1FYNP91on35CJD5QN5rw9Fpa9qOL",
      "sedol": null,
      "ticker_symbol": "DOGE",
      "type": "cryptocurrency",
      "subtype": "cryptocurrency",
      "unofficial_currency_code": null,
      "update_datetime": "2022-06-07T23:01:00Z",
      "market_identifier_code": "XNAS",
      "sector": null,
      "industry": null,
      "option_contract": null,
      "fixed_income": null
    }
  ]
}
```

\=\*=\*=\*=

#### /investments/transactions/get 

#### Get investment transactions 

The [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint allows developers to retrieve up to 24 months of user-authorized transaction data for investment accounts.  
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift.  
Due to the potentially large number of investment transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the `total_investment_transactions` response body field to fetch all available investment transactions.  
Note that Investments does not have a webhook to indicate when initial transaction data has loaded (unless you use the `async_update` option). Instead, if transactions data is not ready when [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) is first called, Plaid will wait for the data. For this reason, calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) immediately after Link may take up to one to two minutes to return.  
Data returned by the asynchronous investments extraction flow (when `async_update` is set to true) may not be immediately available to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) . To be alerted when the data is ready to be fetched, listen for the `HISTORICAL_UPDATE` webhook. If no investments history is ready when [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) is called, it will return a `PRODUCT_NOT_READY` error.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**start\_date** (required, string)  
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: date

**end\_date** (required, string)  
The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: date

**options** (object)  
An optional object to filter /investments/transactions/get results. If provided, must be non-null.

**options->account\_ids** (\[string\])  
An array of account\_ids to retrieve for the Item.

**options->count** (integer)  
The number of transactions to fetch. Default: 100 Minimum: 1 Maximum: 500

**options->offset** (integer)  
The number of transactions to skip when fetching transaction history Default: 0 Minimum: 0

**options->async\_update** (boolean)  
If the Item was not initialized with the investments product via the products, required\_if\_supported\_products, or optional\_products array when calling /link/token/create, and async\_update is set to true, the initial Investments extraction will happen asynchronously. Plaid will subsequently fire a HISTORICAL\_UPDATE webhook when the extraction completes. When false, Plaid will wait to return a response until extraction completion and no HISTORICAL\_UPDATE webhook will fire. Note that while the extraction is happening asynchronously, calls to /investments/transactions/get and /investments/refresh will return PRODUCT\_NOT\_READY errors until the extraction completes. Default: false

```javascript
const request: InvestmentsTransactionsGetRequest = {
  access_token: accessToken,
  start_date: '2019-01-01',
  end_date: '2019-06-10',
};
try {
  const response = await plaidClient.investmentsTransactionsGet(request);
  const investmentTransactions = response.data.investment_transactions;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**accounts** (\[object\])  
The accounts for which transaction history is being fetched.

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**securities** (\[object\])  
All securities for which there is a corresponding transaction being fetched.

**securities->security\_id** (string)  
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security\_id is case sensitive. The security\_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.

**securities->isin** (nullable, string)  
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->cusip** (nullable, string)  
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process here.

**securities->sedol** (deprecated, nullable, string)  
(Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK.

**securities->institution\_security\_id** (nullable, string)  
An identifier given to the security by the institution

**securities->institution\_id** (nullable, string)  
If institution\_security\_id is present, this field indicates the Plaid institution\_id of the institution to whom the identifier belongs.

**securities->proxy\_security\_id** (nullable, string)  
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.

**securities->name** (nullable, string)  
A descriptive name for the security, suitable for display.

**securities->ticker\_symbol** (nullable, string)  
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

**securities->is\_cash\_equivalent** (nullable, boolean)  
Indicates that a security is a highly liquid asset and can be treated like cash.

**securities->type** (nullable, string)  
The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: cash: Cash, currency, and money market funds cryptocurrency: Digital or virtual currencies derivative: Options, warrants, and other derivative instruments equity: Domestic and foreign equities etf: Multi-asset exchange-traded investment funds fixed income: Bonds and certificates of deposit (CDs) loan: Loans and loan receivables mutual fund: Open- and closed-end vehicles pooling funds of multiple investors other: Unknown or other investment types

**securities->subtype** (nullable, string)  
The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: Possible values: asset backed security, bill, bond, bond with warrants, cash, cash management bill, common stock, convertible bond, convertible equity, cryptocurrency, depositary receipt, depositary receipt on debt, etf, float rating note, fund of funds, hedge fund, limited partnership unit, medium term note, money market debt, mortgage backed security, municipal bond, mutual fund, note, option, other, preferred convertible, preferred equity, private equity fund, real estate investment trust, structured equity product, treasury inflation protected securities, unit, warrant.

**securities->close\_price** (nullable, number)  
Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update\_datetime with the time when the price was last updated. Format: double

**securities->close\_price\_as\_of** (nullable, string)  
Date for which close\_price is accurate. Always null if close\_price is null. Format: date

**securities->update\_datetime** (nullable, string)  
Date and time at which close\_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close\_price is null. Format: date-time

**securities->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the price given. Always null if unofficial\_currency\_code is non-null.

**securities->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the security. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**securities->market\_identifier\_code** (nullable, string)  
The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded.

**securities->sector** (nullable, string)  
The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->industry** (nullable, string)  
The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the "Sectors and Industries" spreadsheet.

**securities->option\_contract** (nullable, object)  
Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a custom Sandbox user and the ticker field of the custom security follows the OCC Option Symbol standard with no spaces. For an example of simulating this in Sandbox, see the custom Sandbox GitHub.

**securities->option\_contract->contract\_type** (string)  
The type of this option contract. It is one of: put: for Put option contracts call: for Call option contracts

**securities->option\_contract->expiration\_date** (string)  
The expiration date for this option contract, in ISO 8601 format. Format: date

**securities->option\_contract->strike\_price** (number)  
The strike price for this option contract, per share of security. Format: double

**securities->option\_contract->underlying\_security\_ticker** (string)  
The ticker of the underlying security for this option contract.

**securities->fixed\_income** (nullable, object)  
Details about the fixed income security.

**securities->fixed\_income->yield\_rate** (nullable, object)  
Details about a fixed income security's expected rate of return.

**securities->fixed\_income->yield\_rate->percentage** (number)  
The fixed income security's expected rate of return. Format: double

**securities->fixed\_income->yield\_rate->type** (nullable, string)  
The type of rate which indicates how the predicted yield was calculated. It is one of: coupon: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. coupon\_equivalent: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. discount: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. yield: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: coupon, coupon\_equivalent, discount, yield, null

**securities->fixed\_income->maturity\_date** (nullable, string)  
The maturity date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->issue\_date** (nullable, string)  
The issue date for this fixed income security, in ISO 8601 format. Format: date

**securities->fixed\_income->face\_value** (nullable, number)  
The face value that is paid upon maturity of the fixed income security, per unit of security. Format: double

**investment\_transactions** (\[object\])  
The transactions being fetched

**investment\_transactions->investment\_transaction\_id** (string)  
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment\_transaction\_id is case sensitive.

**investment\_transactions->account\_id** (string)  
The account\_id of the account against which this transaction posted.

**investment\_transactions->security\_id** (nullable, string)  
The security\_id to which this transaction is related.

**investment\_transactions->date** (string)  
The ISO 8601 posting date for the transaction. Format: date

**investment\_transactions->name** (string)  
The institution’s description of the transaction.

**investment\_transactions->quantity** (number)  
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: double

**investment\_transactions->amount** (number)  
The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: double

**investment\_transactions->price** (number)  
The price of the security at which this transaction occurred. Format: double

**investment\_transactions->fees** (nullable, number)  
The combined value of all fees applied to this transaction Format: double

**investment\_transactions->type** (string)  
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: buy, sell, cancel, cash, fee, transfer

**investment\_transactions->subtype** (string)  
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema. Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal

**investment\_transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**investment\_transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the holding. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**total\_investment\_transactions** (integer)  
The total number of transactions available within the date range specified. If total\_investment\_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**is\_investments\_fallback\_item** (boolean)  
When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow.

```json
{
  "accounts": [
    {
      "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",
      "balances": {
        "available": null,
        "current": 320.76,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    }
  ],
  "investment_transactions": [
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -8.72,
      "cancel_transaction_id": null,
      "date": "2020-05-29",
      "fees": 0,
      "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
      "iso_currency_code": "USD",
      "name": "INCOME DIV DIVIDEND RECEIVED",
      "price": 0,
      "quantity": 0,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "subtype": "dividend",
      "type": "cash",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -1289.01,
      "cancel_transaction_id": null,
      "date": "2020-05-28",
      "fees": 7.99,
      "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
      "iso_currency_code": "USD",
      "name": "SELL Matthews Pacific Tiger Fund Insti Class",
      "price": 27.53,
      "quantity": -47.74104242992852,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "subtype": "sell",
      "type": "sell",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": 7.7,
      "cancel_transaction_id": null,
      "date": "2020-05-27",
      "fees": 7.99,
      "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",
      "iso_currency_code": "USD",
      "name": "BUY DoubleLine Total Return Bond Fund",
      "price": 10.42,
      "quantity": 0.7388014749727547,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "subtype": "buy",
      "type": "buy",
      "unofficial_currency_code": null
    }
  ],
  "item": {
    "available_products": [
      "assets",
      "balance",
      "identity",
      "transactions"
    ],
    "billed_products": [
      "auth",
      "investments"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_12",
    "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "iv4q3ZlytOOthkv",
  "securities": [
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "subtype": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Miscellaneous",
      "industry": "Investment Trusts or Mutual Funds",
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 10.42,
      "close_price_as_of": null,
      "cusip": "258620103",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US2586201038",
      "iso_currency_code": "USD",
      "name": "DoubleLine Total Return Bond Fund",
      "proxy_security_id": null,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "sedol": null,
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "subtype": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": null,
      "industry": null,
      "option_contract": null,
      "fixed_income": null
    },
    {
      "close_price": 34.73,
      "close_price_as_of": null,
      "cusip": "84470P109",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US84470P1093",
      "iso_currency_code": "USD",
      "name": "Southside Bancshares Inc.",
      "proxy_security_id": null,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "sedol": null,
      "ticker_symbol": "SBSI",
      "type": "equity",
      "subtype": "common stock",
      "unofficial_currency_code": null,
      "update_datetime": null,
      "market_identifier_code": "XNAS",
      "sector": "Finance",
      "industry": "Regional Banks",
      "option_contract": null,
      "fixed_income": null
    }
  ],
  "total_investment_transactions": 3
}
```

\=\*=\*=\*=

#### /investments/refresh 

#### Refresh investment data 

[/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) is an optional endpoint for users of the Investments product. It initiates an on-demand extraction to fetch the newest investment holdings and transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Investments-enabled Item. If changes to investments are discovered after calling [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) , Plaid will fire webhooks: [HOLDINGS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#holdings-default_update) if any new holdings are detected, and [INVESTMENTS\_TRANSACTIONS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-default_update) if any new investment transactions are detected. This webhook will typically not fire in the Sandbox environment, due to the lack of dynamic investment transactions and holdings data. To test this webhook in Sandbox, call [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) . Updated holdings and investment transactions can be fetched by calling [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) and [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) . Note that the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint is not supported by all institutions. If called on an Item from an institution that does not support this functionality, it will return a `PRODUCT_NOT_SUPPORTED` error.  
As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests.  
[/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) is offered as an add-on to Investments and has a separate [fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

```javascript
const request: InvestmentsRefreshRequest = {
  access_token: accessToken,
};
try {
  await plaidClient.investmentsRefresh(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "1vwmF5TBQwiqfwP"
}
```

### Webhooks 

Updates are sent to indicate that new holdings or investment transactions are available.

\=\*=\*=\*=

#### HOLDINGS: DEFAULT\_UPDATE 

Fired when new or updated holdings have been detected on an investment account. The webhook typically fires in response to any newly added holdings or price changes to existing holdings, most commonly after market close.

#### Properties 

**webhook\_type** (string)  
HOLDINGS

**webhook\_code** (string)  
DEFAULT\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**new\_holdings** (number)  
The number of new holdings reported since the last time this webhook was fired.

**updated\_holdings** (number)  
The number of updated holdings reported since the last time this webhook was fired.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "HOLDINGS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_holdings": 19,
  "updated_holdings": 0,
  "environment": "production"
}
```

\=\*=\*=\*=

#### INVESTMENTS\_TRANSACTIONS: DEFAULT\_UPDATE 

Fired when new transactions have been detected on an investment account.

#### Properties 

**webhook\_type** (string)  
INVESTMENTS\_TRANSACTIONS

**webhook\_code** (string)  
DEFAULT\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**new\_investments\_transactions** (number)  
The number of new transactions reported since the last time this webhook was fired.

**canceled\_investments\_transactions** (number)  
The number of canceled transactions reported since the last time this webhook was fired.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "INVESTMENTS_TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_investments_transactions": 16,
  "canceled_investments_transactions": 0,
  "environment": "production"
}
```

\=\*=\*=\*=

#### INVESTMENTS\_TRANSACTIONS: HISTORICAL\_UPDATE 

Fired after an asynchronous extraction on an investments account.

#### Properties 

**webhook\_type** (string)  
INVESTMENTS\_TRANSACTIONS

**webhook\_code** (string)  
HISTORICAL\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**new\_investments\_transactions** (number)  
The number of new transactions reported since the last time this webhook was fired.

**canceled\_investments\_transactions** (number)  
The number of canceled transactions reported since the last time this webhook was fired.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "INVESTMENTS_TRANSACTIONS",
  "webhook_code": "HISTORICAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_investments_transactions": 16,
  "canceled_investments_transactions": 0,
  "environment": "production"
}
```

---


# API - Layer | Plaid Docs

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 |

### 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](https://plaid.com/docs/link/index.html.md#link-flow-overview) .

#### 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** (required, string)  
The id of a template defined in Plaid Dashboard

**user** (object)  
SessionTokenCreateRequestUser defines per-session user-specific data for /session/token/create. Required if the root-level user\_id field isn't included.

**user->client\_user\_id** (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.

**user->user\_id** (string)  
The Plaid user\_id of the User associated with this webhook, warning, or error.

**user\_id** (string)  
A unique ID generated by Plaid representing the end user. Typically this ID will come from the /user/create response, when the endpoint is invoked with the PLAID-NEW-USER-API-ENABLED header. Required if the user object isn't included. If this field is included, then the remaining user object fields are ignored.

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

**android\_package\_name** (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. 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** (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.

```javascript
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
}
```

#### 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->link\_token** (string)  
A Link token, which can be supplied to Link in order to initialize it and receive a public\_token.

**link->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

```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 

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

#### 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** (required, string)  
The public token generated by the end user Layer session.

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

#### Response fields and example 

**identity** (nullable, object)  
The identity data permissioned by the end user during the authorization flow.

**identity->name** (nullable, object)  
The user's first name and last name.

string

string

**identity->address** (nullable, object)  
The user's address.

**identity->address->city** (nullable, string)  
The full city name

**identity->address->region** (nullable, string)  
The region or state. Example: "NC"

**identity->address->street** (nullable, string)  
The full street address Example: "564 Main Street, APT 15"

**identity->address->street2** (nullable, string)  
The second line street address

**identity->address->postal\_code** (nullable, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**identity->address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**identity->phone\_number** (string)  
The user's phone number in E.164 format

**identity->email** (nullable, string)  
The user's email address. Note: email is currently not returned for users, and will be added later in 2025.

**identity->date\_of\_birth** (nullable, string)  
The user's date of birth.

**identity->ssn** (nullable, string)  
The user's social security number.

**identity->ssn\_last\_4** (nullable, string)  
The last 4 digits of the user's social security number.

string

**items** (\[object\])  
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.

**items->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.

```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"
  },
  "items": [
    {
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0"
    }
  ],
  "request_id": "m8MDnv9okwxFNBV"
}
```

### 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** (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

```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"
}
```

---


# API - Liabilities | Plaid Docs

Liabilities 
============

#### API reference for Liabilities endpoints and webhooks 

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

| Endpoints |  |
| --- | --- |
| [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) | Fetch liabilities data |

| Webhooks |  |
| --- | --- |
| [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/liabilities/index.html.md#default_update) | New or updated liabilities available |

### Endpoints 

\=\*=\*=\*=

#### /liabilities/get 

#### Retrieve Liabilities data 

The [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) endpoint returns various details about an Item with loan or credit accounts. Liabilities data is available primarily for US financial institutions, with some limited coverage of Canadian institutions. Currently supported account types are account type `credit` with account subtype `credit card` or `paypal`, and account type `loan` with account subtype `student` or `mortgage`. To limit accounts listed in Link to types and subtypes supported by Liabilities, you can use the `account_filters` parameter when [creating a Link token](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .  
The types of information returned by Liabilities can include balances and due dates, loan terms, and account details such as original loan amount and guarantor. Data is refreshed approximately once per day; the latest data can be retrieved by calling [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**options** (object)  
An optional object to filter /liabilities/get results. If provided, options cannot be null.

**options->account\_ids** (\[string\])  
A list of accounts to retrieve for the Item. An error will be returned if a provided account\_id is not associated with the Item

```javascript
// Retrieve Liabilities data for an Item
const request: LiabilitiesGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.liabilitiesGet(request);
  const liabilities = response.data.liabilities;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
An array of accounts associated with the Item

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**liabilities** (object)  
An object containing liability accounts

**liabilities->credit** (nullable, \[object\])  
The credit accounts returned.

**liabilities->credit->account\_id** (nullable, string)  
The ID of the account that this liability belongs to.

**liabilities->credit->aprs** (\[object\])  
The various interest rates that apply to the account. APR information is not provided by all card issuers; if APR data is not available, this array will be empty.

**liabilities->credit->aprs->apr\_percentage** (number)  
Annual Percentage Rate applied. Format: double

**liabilities->credit->aprs->apr\_type** (string)  
The type of balance to which the APR applies. Possible values: balance\_transfer\_apr, cash\_apr, purchase\_apr, special

**liabilities->credit->aprs->balance\_subject\_to\_apr** (nullable, number)  
Amount of money that is subjected to the APR if a balance was carried beyond payment due date. How it is calculated can vary by card issuer. It is often calculated as an average daily balance. Format: double

**liabilities->credit->aprs->interest\_charge\_amount** (nullable, number)  
Amount of money charged due to interest from last statement. Format: double

**liabilities->credit->is\_overdue** (nullable, boolean)  
true if a payment is currently overdue. Availability for this field is limited.

**liabilities->credit->last\_payment\_amount** (nullable, number)  
The amount of the last payment. Format: double

**liabilities->credit->last\_payment\_date** (nullable, string)  
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Availability for this field is limited. Format: date

**liabilities->credit->last\_statement\_issue\_date** (nullable, string)  
The date of the last statement. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->credit->last\_statement\_balance** (nullable, number)  
The total amount owed as of the last statement issued Format: double

**liabilities->credit->minimum\_payment\_amount** (nullable, number)  
The minimum payment due for the next billing cycle. Format: double

**liabilities->credit->next\_payment\_due\_date** (nullable, string)  
The due date for the next payment. The due date is null if a payment is not expected. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage** (nullable, \[object\])  
The mortgage accounts returned.

**liabilities->mortgage->account\_id** (string)  
The ID of the account that this liability belongs to.

**liabilities->mortgage->account\_number** (nullable, string)  
The account number of the loan.

**liabilities->mortgage->current\_late\_fee** (nullable, number)  
The current outstanding amount charged for late payment. Format: double

**liabilities->mortgage->escrow\_balance** (nullable, number)  
Total amount held in escrow to pay taxes and insurance on behalf of the borrower. Format: double

**liabilities->mortgage->has\_pmi** (nullable, boolean)  
Indicates whether the borrower has private mortgage insurance in effect.

**liabilities->mortgage->has\_prepayment\_penalty** (nullable, boolean)  
Indicates whether the borrower will pay a penalty for early payoff of mortgage.

**liabilities->mortgage->interest\_rate** (object)  
Object containing metadata about the interest rate for the mortgage.

**liabilities->mortgage->interest\_rate->percentage** (nullable, number)  
Percentage value (interest rate of current mortgage, not APR) of interest payable on a loan. Format: double

**liabilities->mortgage->interest\_rate->type** (nullable, string)  
The type of interest charged (fixed or variable).

**liabilities->mortgage->last\_payment\_amount** (nullable, number)  
The amount of the last payment. Format: double

**liabilities->mortgage->last\_payment\_date** (nullable, string)  
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->loan\_type\_description** (nullable, string)  
Description of the type of loan, for example conventional, fixed, or variable. This field is provided directly from the loan servicer and does not have an enumerated set of possible values.

**liabilities->mortgage->loan\_term** (nullable, string)  
Full duration of mortgage as at origination (e.g. 10 year).

**liabilities->mortgage->maturity\_date** (nullable, string)  
Original date on which mortgage is due in full. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->next\_monthly\_payment** (nullable, number)  
The amount of the next payment. Format: double

**liabilities->mortgage->next\_payment\_due\_date** (nullable, string)  
The due date for the next payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->origination\_date** (nullable, string)  
The date on which the loan was initially lent. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->mortgage->origination\_principal\_amount** (nullable, number)  
The original principal balance of the mortgage. Format: double

**liabilities->mortgage->past\_due\_amount** (nullable, number)  
Amount of loan (principal + interest) past due for payment. Format: double

**liabilities->mortgage->property\_address** (object)  
Object containing fields describing property address.

**liabilities->mortgage->property\_address->city** (nullable, string)  
The city name.

**liabilities->mortgage->property\_address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code.

**liabilities->mortgage->property\_address->postal\_code** (nullable, string)  
The five or nine digit postal code.

**liabilities->mortgage->property\_address->region** (nullable, string)  
The region or state (example "NC").

**liabilities->mortgage->property\_address->street** (nullable, string)  
The full street address (example "564 Main Street, Apt 15").

**liabilities->mortgage->ytd\_interest\_paid** (nullable, number)  
The year to date (YTD) interest paid. Format: double

**liabilities->mortgage->ytd\_principal\_paid** (nullable, number)  
The YTD principal paid. Format: double

**liabilities->student** (nullable, \[object\])  
The student loan accounts returned.

**liabilities->student->account\_id** (nullable, string)  
The ID of the account that this liability belongs to. Each account can only contain one liability.

**liabilities->student->account\_number** (nullable, string)  
The account number of the loan. For some institutions, this may be a masked version of the number (e.g., the last 4 digits instead of the entire number).

**liabilities->student->disbursement\_dates** (nullable, \[string\])  
The dates on which loaned funds were disbursed or will be disbursed. These are often in the past. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->expected\_payoff\_date** (nullable, string)  
The date when the student loan is expected to be paid off. Availability for this field is limited. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->guarantor** (nullable, string)  
The guarantor of the student loan.

**liabilities->student->interest\_rate\_percentage** (number)  
The interest rate on the loan as a percentage. Format: double

**liabilities->student->is\_overdue** (nullable, boolean)  
true if a payment is currently overdue. Availability for this field is limited.

**liabilities->student->last\_payment\_amount** (nullable, number)  
The amount of the last payment. Format: double

**liabilities->student->last\_payment\_date** (nullable, string)  
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->last\_statement\_balance** (nullable, number)  
The total amount owed as of the last statement issued Format: double

**liabilities->student->last\_statement\_issue\_date** (nullable, string)  
The date of the last statement. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->loan\_name** (nullable, string)  
The type of loan, e.g., "Consolidation Loans".

**liabilities->student->loan\_status** (object)  
An object representing the status of the student loan

**liabilities->student->loan\_status->end\_date** (nullable, string)  
The date until which the loan will be in its current status. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->loan\_status->type** (nullable, string)  
The status type of the student loan Possible values: cancelled, charged off, claim, consolidated, deferment, delinquent, discharged, extension, forbearance, in grace, in military, in school, not fully disbursed, other, paid in full, refunded, repayment, transferred, pending idr

**liabilities->student->minimum\_payment\_amount** (nullable, number)  
The minimum payment due for the next billing cycle. There are some exceptions: Some institutions require a minimum payment across all loans associated with an account number. Our API presents that same minimum payment amount on each loan. The institutions that do this are: Great Lakes ( ins\_116861), Firstmark (ins\_116295), Commonbond Firstmark Services (ins\_116950), Granite State (ins\_116308), and Oklahoma Student Loan Authority (ins\_116945). Firstmark (ins\_116295 ) and Navient (ins\_116248) will display as $0 if there is an autopay program in effect. Format: double

**liabilities->student->next\_payment\_due\_date** (nullable, string)  
The due date for the next payment. The due date is null if a payment is not expected. A payment is not expected if loan\_status.type is deferment, in\_school, consolidated, paid in full, or transferred. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->origination\_date** (nullable, string)  
The date on which the loan was initially lent. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: date

**liabilities->student->origination\_principal\_amount** (nullable, number)  
The original principal balance of the loan. Format: double

**liabilities->student->outstanding\_interest\_amount** (nullable, number)  
The total dollar amount of the accrued interest balance. For Sallie Mae ( ins\_116944), this amount is included in the current balance of the loan, so this field will return as null. Format: double

**liabilities->student->payment\_reference\_number** (nullable, string)  
The relevant account number that should be used to reference this loan for payments. In the majority of cases, payment\_reference\_number will match account\_number, but in some institutions, such as Great Lakes (ins\_116861), it will be different.

**liabilities->student->repayment\_plan** (object)  
An object representing the repayment plan for the student loan

**liabilities->student->repayment\_plan->description** (nullable, string)  
The description of the repayment plan as provided by the servicer.

**liabilities->student->repayment\_plan->type** (nullable, string)  
The type of the repayment plan. Possible values: extended graduated, extended standard, graduated, income-contingent repayment, income-based repayment, income-sensitive repayment, interest-only, other, pay as you earn, revised pay as you earn, standard, saving on a valuable education, null

**liabilities->student->sequence\_number** (nullable, string)  
The sequence number of the student loan. Heartland ECSI (ins\_116948) does not make this field available.

**liabilities->student->servicer\_address** (object)  
The address of the student loan servicer. This is generally the remittance address to which payments should be sent.

**liabilities->student->servicer\_address->city** (nullable, string)  
The full city name

**liabilities->student->servicer\_address->region** (nullable, string)  
The region or state Example: "NC"

**liabilities->student->servicer\_address->street** (nullable, string)  
The full street address Example: "564 Main Street, APT 15"

**liabilities->student->servicer\_address->postal\_code** (nullable, string)  
The postal code

**liabilities->student->servicer\_address->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code

**liabilities->student->ytd\_interest\_paid** (nullable, number)  
The year to date (YTD) interest paid. Availability for this field is limited. Format: double

**liabilities->student->ytd\_principal\_paid** (nullable, number)  
The year to date (YTD) principal paid. Availability for this field is limited. Format: double

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "balances": {
        "available": null,
        "current": 410,
        "iso_currency_code": "USD",
        "limit": 2000,
        "unofficial_currency_code": null
      },
      "mask": "3333",
      "name": "Plaid Credit Card",
      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
      "subtype": "credit card",
      "type": "credit"
    },
    {
      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    },
    {
      "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
      "balances": {
        "available": null,
        "current": 56302.06,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "8888",
      "name": "Plaid Mortgage",
      "official_name": null,
      "subtype": "mortgage",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "identity",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "institution_name": "Chase",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "liabilities": {
    "credit": [
      {
        "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
        "aprs": [
          {
            "apr_percentage": 15.24,
            "apr_type": "balance_transfer_apr",
            "balance_subject_to_apr": 1562.32,
            "interest_charge_amount": 130.22
          },
          {
            "apr_percentage": 27.95,
            "apr_type": "cash_apr",
            "balance_subject_to_apr": 56.22,
            "interest_charge_amount": 14.81
          },
          {
            "apr_percentage": 12.5,
            "apr_type": "purchase_apr",
            "balance_subject_to_apr": 157.01,
            "interest_charge_amount": 25.66
          },
          {
            "apr_percentage": 0,
            "apr_type": "special",
            "balance_subject_to_apr": 1000,
            "interest_charge_amount": 0
          }
        ],
        "is_overdue": false,
        "last_payment_amount": 168.25,
        "last_payment_date": "2019-05-22",
        "last_statement_issue_date": "2019-05-28",
        "last_statement_balance": 1708.77,
        "minimum_payment_amount": 20,
        "next_payment_due_date": "2020-05-28"
      }
    ],
    "mortgage": [
      {
        "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
        "account_number": "3120194154",
        "current_late_fee": 25,
        "escrow_balance": 3141.54,
        "has_pmi": true,
        "has_prepayment_penalty": true,
        "interest_rate": {
          "percentage": 3.99,
          "type": "fixed"
        },
        "last_payment_amount": 3141.54,
        "last_payment_date": "2019-08-01",
        "loan_term": "30 year",
        "loan_type_description": "conventional",
        "maturity_date": "2045-07-31",
        "next_monthly_payment": 3141.54,
        "next_payment_due_date": "2019-11-15",
        "origination_date": "2015-08-01",
        "origination_principal_amount": 425000,
        "past_due_amount": 2304,
        "property_address": {
          "city": "Malakoff",
          "country": "US",
          "postal_code": "14236",
          "region": "NY",
          "street": "2992 Cameron Road"
        },
        "ytd_interest_paid": 12300.4,
        "ytd_principal_paid": 12340.5
      }
    ],
    "student": [
      {
        "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
        "account_number": "4277075694",
        "disbursement_dates": [
          "2002-08-28"
        ],
        "expected_payoff_date": "2032-07-28",
        "guarantor": "DEPT OF ED",
        "interest_rate_percentage": 5.25,
        "is_overdue": false,
        "last_payment_amount": 138.05,
        "last_payment_date": "2019-04-22",
        "last_statement_issue_date": "2019-04-28",
        "last_statement_balance": 1708.77,
        "loan_name": "Consolidation",
        "loan_status": {
          "end_date": "2032-07-28",
          "type": "repayment"
        },
        "minimum_payment_amount": 25,
        "next_payment_due_date": "2019-05-28",
        "origination_date": "2002-08-28",
        "origination_principal_amount": 25000,
        "outstanding_interest_amount": 6227.36,
        "payment_reference_number": "4277075694",
        "pslf_status": {
          "estimated_eligibility_date": "2021-01-01",
          "payments_made": 200,
          "payments_remaining": 160
        },
        "repayment_plan": {
          "description": "Standard Repayment",
          "type": "standard"
        },
        "sequence_number": "1",
        "servicer_address": {
          "city": "San Matias",
          "country": "US",
          "postal_code": "99415",
          "region": "CA",
          "street": "123 Relaxation Road"
        },
        "ytd_interest_paid": 280.55,
        "ytd_principal_paid": 271.65
      }
    ]
  },
  "request_id": "dTnnm60WgKGLnKL"
}
```

### Webhooks 

Liabilities webhooks are sent to indicate that new loans or updated loan fields for existing accounts are available.

\=\*=\*=\*=

#### DEFAULT\_UPDATE 

The webhook of type `LIABILITIES` and code `DEFAULT_UPDATE` will be fired when new or updated liabilities have been detected on a liabilities item.

#### Properties 

**webhook\_type** (string)  
LIABILITIES

**webhook\_code** (string)  
DEFAULT\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**account\_ids\_with\_new\_liabilities** (\[string\])  
An array of account\_id's for accounts that contain new liabilities.'

**account\_ids\_with\_updated\_liabilities** (object)  
An object with keys of account\_id's that are mapped to their respective liabilities fields that changed. Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": \["past\_amount\_due"\] }

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "LIABILITIES",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "account_ids_with_new_liabilities": [
    "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
  ],
  "account_ids_with_updated_liabilities": {
    "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [
      "past_amount_due"
    ]
  },
  "environment": "production"
}
```

---


# API - Monitor | Plaid Docs

Monitor 
========

#### API reference for Monitor endpoints and webhooks 

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

| Endpoints |  |
| --- | --- |
| [/watchlist\_screening/individual/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualcreate) | Create a watchlist screening for a person |
| [/watchlist\_screening/individual/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualget) | Retrieve an individual watchlist screening |
| [/watchlist\_screening/individual/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividuallist) | List individual watchlist screenings |
| [/watchlist\_screening/individual/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualupdate) | Update individual watchlist screening |
| [/watchlist\_screening/individual/history/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhistorylist) | List history for entity watchlist screenings |
| [/watchlist\_screening/individual/review/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualreviewcreate) | Create a review for an individual watchlist screening |
| [/watchlist\_screening/individual/review/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualreviewlist) | List reviews for individual watchlist screenings |
| [/watchlist\_screening/individual/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhitlist) | List hits for individual watchlist screenings |
| [/watchlist\_screening/individual/program/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualprogramget) | Get individual watchlist screening programs |
| [/watchlist\_screening/individual/program/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualprogramlist) | List individual watchlist screening programs |
| [/watchlist\_screening/entity/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitycreate) | Create a watchlist screening for an entity |
| [/watchlist\_screening/entity/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityget) | Retrieve an individual watchlist screening |
| [/watchlist\_screening/entity/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitylist) | List individual watchlist screenings |
| [/watchlist\_screening/entity/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityupdate) | Update individual watchlist screening |
| [/watchlist\_screening/entity/history/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhistorylist) | List history for individual watchlist screenings |
| [/watchlist\_screening/entity/review/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityreviewcreate) | Create a review for an individual watchlist screening |
| [/watchlist\_screening/entity/review/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityreviewlist) | List reviews for individual watchlist screenings |
| [/watchlist\_screening/entity/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhitlist) | List hits for individual watchlist screenings |
| [/watchlist\_screening/entity/program/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityprogramget) | Get individual watchlist screening programs |
| [/watchlist\_screening/entity/program/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityprogramlist) | List individual watchlist screening programs |

| See also |  |
| --- | --- |
| [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user |
| [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users |

| Webhooks |  |
| --- | --- |
| [SCREENING: STATUS\_UPDATED](https://plaid.com/docs/api/products/monitor/index.html.md#screening-status_updated) | The status of an individual watchlist screening has changed |
| [ENTITY\_SCREENING: STATUS\_UPDATED](https://plaid.com/docs/api/products/monitor/index.html.md#entity_screening-status_updated) | The status of an entity watchlist screening has changed |

### Endpoints 

\=\*=\*=\*=

#### /watchlist\_screening/individual/create 

#### Create a watchlist screening for a person 

Create a new Watchlist Screening to check your customer against watchlists defined in the associated Watchlist Program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

#### Request fields 

**search\_terms** (required, object)  
Search inputs for creating a watchlist screening

**search\_terms->watchlist\_program\_id** (required, string)  
ID of the associated program.

**search\_terms->legal\_name** (required, string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**search\_terms->document\_number** (string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

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

```javascript
const request: WatchlistScreeningIndividualCreateRequest = {
  search_terms: {
    watchlist_program_id: 'prg_2eRPsDnL66rZ7H',
    legal_name: 'Aleksey Potemkin',
    date_of_birth: '1990-05-29',
    document_number: 'C31195855',
    country: 'US',
  },
  client_user_id: 'example-client-user-id-123',
};


try {
  const response = await client.watchlistScreeningIndividualCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated screening.

**search\_terms** (object)  
Search terms for creating an individual watchlist screening

**search\_terms->watchlist\_program\_id** (string)  
ID of the associated program.

**search\_terms->legal\_name** (string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "scr_52xR9LKo77r1Np",
  "search_terms": {
    "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
    "legal_name": "Aleksey Potemkin",
    "date_of_birth": "1990-05-29",
    "document_number": "C31195855",
    "country": "US",
    "version": 1
  },
  "assignee": "54350110fedcbaf01234ffee",
  "status": "cleared",
  "client_user_id": "your-db-id-3b24110",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/get 

#### Retrieve an individual watchlist screening 

Retrieve a previously created individual watchlist screening

#### Request fields 

**watchlist\_screening\_id** (required, string)  
ID of the associated screening.

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

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

```javascript
const request: WatchlistScreeningIndividualGetRequest = {
  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningIndividualGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated screening.

**search\_terms** (object)  
Search terms for creating an individual watchlist screening

**search\_terms->watchlist\_program\_id** (string)  
ID of the associated program.

**search\_terms->legal\_name** (string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "scr_52xR9LKo77r1Np",
  "search_terms": {
    "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
    "legal_name": "Aleksey Potemkin",
    "date_of_birth": "1990-05-29",
    "document_number": "C31195855",
    "country": "US",
    "version": 1
  },
  "assignee": "54350110fedcbaf01234ffee",
  "status": "cleared",
  "client_user_id": "your-db-id-3b24110",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/list 

#### List Individual Watchlist Screenings 

List previously created watchlist screenings for individuals

#### Request fields 

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

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

**watchlist\_program\_id** (required, string)  
ID of the associated program.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**assignee** (string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningIndividualListRequest = {
  watchlist_program_id: 'prg_2eRPsDnL66rZ7H',
  client_user_id: 'example-client-user-id-123',
};


try {
  const response = await client.watchlistScreeningIndividualList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**watchlist\_screenings** (\[object\])  
List of individual watchlist screenings

**watchlist\_screenings->id** (string)  
ID of the associated screening.

**watchlist\_screenings->search\_terms** (object)  
Search terms for creating an individual watchlist screening

**watchlist\_screenings->search\_terms->watchlist\_program\_id** (string)  
ID of the associated program.

**watchlist\_screenings->search\_terms->legal\_name** (string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**watchlist\_screenings->search\_terms->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**watchlist\_screenings->search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**watchlist\_screenings->search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**watchlist\_screenings->search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**watchlist\_screenings->assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**watchlist\_screenings->status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**watchlist\_screenings->client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**watchlist\_screenings->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**watchlist\_screenings->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**watchlist\_screenings->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**watchlist\_screenings->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "watchlist_screenings": [
    {
      "id": "scr_52xR9LKo77r1Np",
      "search_terms": {
        "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
        "legal_name": "Aleksey Potemkin",
        "date_of_birth": "1990-05-29",
        "document_number": "C31195855",
        "country": "US",
        "version": 1
      },
      "assignee": "54350110fedcbaf01234ffee",
      "status": "cleared",
      "client_user_id": "your-db-id-3b24110",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/update 

#### Update individual watchlist screening 

Update a specific individual watchlist screening. This endpoint can be used to add additional customer information, correct outdated information, add a reference id, assign the individual to a reviewer, and update which program it is associated with. Please note that you may not update `search_terms` and `status` at the same time since editing `search_terms` may trigger an automatic `status` change.

#### Request fields 

**watchlist\_screening\_id** (required, string)  
ID of the associated screening.

**search\_terms** (object)  
Search terms for editing an individual watchlist screening

**search\_terms->watchlist\_program\_id** (string)  
ID of the associated program.

**search\_terms->legal\_name** (string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->date\_of\_birth** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**search\_terms->document\_number** (string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**assignee** (string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

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

**reset\_fields** (\[string\])  
A list of fields to reset back to null Possible values: assignee

```javascript
const request: WatchlistScreeningIndividualUpdateRequest = {
  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
  status: 'cleared',
};


try {
  const response = await client.watchlistScreeningIndividualUpdate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated screening.

**search\_terms** (object)  
Search terms for creating an individual watchlist screening

**search\_terms->watchlist\_program\_id** (string)  
ID of the associated program.

**search\_terms->legal\_name** (string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "scr_52xR9LKo77r1Np",
  "search_terms": {
    "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
    "legal_name": "Aleksey Potemkin",
    "date_of_birth": "1990-05-29",
    "document_number": "C31195855",
    "country": "US",
    "version": 1
  },
  "assignee": "54350110fedcbaf01234ffee",
  "status": "cleared",
  "client_user_id": "your-db-id-3b24110",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/history/list 

#### List history for individual watchlist screenings 

List all changes to the individual watchlist screening in reverse-chronological order. If the watchlist screening has not been edited, no history will be returned.

#### Request fields 

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

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

**watchlist\_screening\_id** (required, string)  
ID of the associated screening.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningIndividualHistoryListRequest = {
  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningIndividualHistoryList(
    request,
  );
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**watchlist\_screenings** (\[object\])  
List of individual watchlist screenings

**watchlist\_screenings->id** (string)  
ID of the associated screening.

**watchlist\_screenings->search\_terms** (object)  
Search terms for creating an individual watchlist screening

**watchlist\_screenings->search\_terms->watchlist\_program\_id** (string)  
ID of the associated program.

**watchlist\_screenings->search\_terms->legal\_name** (string)  
The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**watchlist\_screenings->search\_terms->date\_of\_birth** (nullable, string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**watchlist\_screenings->search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**watchlist\_screenings->search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**watchlist\_screenings->search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**watchlist\_screenings->assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**watchlist\_screenings->status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**watchlist\_screenings->client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**watchlist\_screenings->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**watchlist\_screenings->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**watchlist\_screenings->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**watchlist\_screenings->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "watchlist_screenings": [
    {
      "id": "scr_52xR9LKo77r1Np",
      "search_terms": {
        "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
        "legal_name": "Aleksey Potemkin",
        "date_of_birth": "1990-05-29",
        "document_number": "C31195855",
        "country": "US",
        "version": 1
      },
      "assignee": "54350110fedcbaf01234ffee",
      "status": "cleared",
      "client_user_id": "your-db-id-3b24110",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/review/create 

#### Create a review for an individual watchlist screening 

Create a review for the individual watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid.

#### Request fields 

**confirmed\_hits** (required, \[string\])  
Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

**dismissed\_hits** (required, \[string\])  
Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

**comment** (string)  
A comment submitted by a team member as part of reviewing a watchlist screening.

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

**watchlist\_screening\_id** (required, string)  
ID of the associated screening.

```javascript
const request: WatchlistScreeningIndividualReviewCreateRequest = {
  confirmed_hits: ['scrhit_52xR9LKo77r1Np'],
  dismissed_hits: [],
  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningIndividualReviewCreate(
    request,
  );
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated review.

**confirmed\_hits** (\[string\])  
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

**dismissed\_hits** (\[string\])  
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

**comment** (nullable, string)  
A comment submitted by a team member as part of reviewing a watchlist screening.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "rev_aCLNRxK3UVzn2r",
  "confirmed_hits": [
    "scrhit_52xR9LKo77r1Np"
  ],
  "dismissed_hits": [
    "scrhit_52xR9LKo77r1Np"
  ],
  "comment": "These look like legitimate matches, rejecting the customer.",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/review/list 

#### List reviews for individual watchlist screenings 

List all reviews for the individual watchlist screening.

#### Request fields 

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

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

**watchlist\_screening\_id** (required, string)  
ID of the associated screening.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningIndividualReviewListRequest = {
  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningIndividualReviewList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**watchlist\_screening\_reviews** (\[object\])  
List of screening reviews

**watchlist\_screening\_reviews->id** (string)  
ID of the associated review.

**watchlist\_screening\_reviews->confirmed\_hits** (\[string\])  
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

**watchlist\_screening\_reviews->dismissed\_hits** (\[string\])  
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

**watchlist\_screening\_reviews->comment** (nullable, string)  
A comment submitted by a team member as part of reviewing a watchlist screening.

**watchlist\_screening\_reviews->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**watchlist\_screening\_reviews->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**watchlist\_screening\_reviews->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**watchlist\_screening\_reviews->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "watchlist_screening_reviews": [
    {
      "id": "rev_aCLNRxK3UVzn2r",
      "confirmed_hits": [
        "scrhit_52xR9LKo77r1Np"
      ],
      "dismissed_hits": [
        "scrhit_52xR9LKo77r1Np"
      ],
      "comment": "These look like legitimate matches, rejecting the customer.",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/hit/list 

#### List hits for individual watchlist screening 

List all hits found by Plaid for a particular individual watchlist screening.

#### Request fields 

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

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

**watchlist\_screening\_id** (required, string)  
ID of the associated screening.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningIndividualHitListRequest = {
  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningIndividualHitList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**watchlist\_screening\_hits** (\[object\])  
List of individual watchlist screening hits

**watchlist\_screening\_hits->id** (string)  
ID of the associated screening hit.

**watchlist\_screening\_hits->review\_status** (string)  
The current state of review. All watchlist screening hits begin in a pending\_review state but can be changed by creating a review. When a hit is in the pending\_review state, it will always show the latest version of the watchlist data Plaid has available and be compared against the latest customer information saved in the watchlist screening. Once a hit has been marked as confirmed or dismissed it will no longer be updated so that the state is as it was when the review was first conducted. Possible values: confirmed, pending\_review, dismissed

**watchlist\_screening\_hits->first\_active** (string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_screening\_hits->inactive\_since** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_screening\_hits->historical\_since** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_screening\_hits->list\_code** (string)  
Shorthand identifier for a specific screening list for individuals. AU\_CON: Australia Department of Foreign Affairs and Trade Consolidated List CA\_CON: Government of Canada Consolidated List of Sanctions EU\_CON: European External Action Service Consolidated List IZ\_CIA: CIA List of Chiefs of State and Cabinet Members IZ\_IPL: Interpol Red Notices for Wanted Persons List IZ\_PEP: Politically Exposed Persons List IZ\_UNC: United Nations Consolidated Sanctions IZ\_WBK: World Bank Listing of Ineligible Firms and Individuals UK\_HMC: UK HM Treasury Consolidated List US\_DPL: Bureau of Industry and Security Denied Persons List US\_DTC: US Department of State AECA Debarred US\_FBI: US Department of Justice FBI Wanted List US\_FSE: US OFAC Foreign Sanctions Evaders US\_ISN: US Department of State Nonproliferation Sanctions US\_PLC: US OFAC Palestinian Legislative Council US\_SAM: US System for Award Management Exclusion List US\_SDN: US OFAC Specially Designated Nationals List US\_SSI: US OFAC Sectoral Sanctions Identifications SG\_SOF: Government of Singapore Terrorists and Terrorist Entities TR\_TWL: Government of Turkey Terrorist Wanted List TR\_DFD: Government of Turkey Domestic Freezing Decisions TR\_FOR: Government of Turkey Foreign Freezing Requests TR\_WMD: Government of Turkey Weapons of Mass Destruction TR\_CMB: Government of Turkey Capital Markets Board Possible values: AU\_CON, CA\_CON, EU\_CON, IZ\_CIA, IZ\_IPL, IZ\_PEP, IZ\_UNC, IZ\_WBK, UK\_HMC, US\_DPL, US\_DTC, US\_FBI, US\_FSE, US\_ISN, US\_MBS, US\_PLC, US\_SAM, US\_SDN, US\_SSI, SG\_SOF, TR\_TWL, TR\_DFD, TR\_FOR, TR\_WMD, TR\_CMB

**watchlist\_screening\_hits->plaid\_uid** (string)  
A universal identifier for a watchlist individual that is stable across searches and updates.

**watchlist\_screening\_hits->source\_uid** (nullable, string)  
The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

**watchlist\_screening\_hits->analysis** (object)  
Analysis information describing why a screening hit matched the provided user information

**watchlist\_screening\_hits->analysis->dates\_of\_birth** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->analysis->documents** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->analysis->locations** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->analysis->names** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->analysis->search\_terms\_version** (integer)  
The version of the screening's search\_terms that were compared when the screening hit was added. screening hits are immutable once they have been reviewed. If changes are detected due to updates to the screening's search\_terms, the associated program, or the list's source data prior to review, the screening hit will be updated to reflect those changes.

**watchlist\_screening\_hits->data** (object)  
Information associated with the watchlist hit

**watchlist\_screening\_hits->data->dates\_of\_birth** (\[object\])  
Dates of birth associated with the watchlist hit

**watchlist\_screening\_hits->data->dates\_of\_birth->analysis** (object)  
Summary object reflecting the match result of the associated data

**watchlist\_screening\_hits->data->dates\_of\_birth->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->data->dates\_of\_birth->data** (object)  
A date range with a start and end date

**watchlist\_screening\_hits->data->dates\_of\_birth->data->beginning** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**watchlist\_screening\_hits->data->dates\_of\_birth->data->ending** (string)  
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: date

**watchlist\_screening\_hits->data->documents** (\[object\])  
Documents associated with the watchlist hit

**watchlist\_screening\_hits->data->documents->analysis** (object)  
Summary object reflecting the match result of the associated data

**watchlist\_screening\_hits->data->documents->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->data->documents->data** (object)  
An official document, usually issued by a governing body or institution, with an associated identifier.

**watchlist\_screening\_hits->data->documents->data->type** (string)  
The kind of official document represented by this object. birth\_certificate - A certificate of birth drivers\_license - A license to operate a motor vehicle immigration\_number - Immigration or residence documents military\_id - Identification issued by a military group other - Any document not covered by other categories passport - An official passport issue by a government personal\_identification - Any generic personal identification that is not covered by other categories ration\_card - Identification that entitles the holder to rations ssn - United States Social Security Number student\_id - Identification issued by an educational institution tax\_id - Identification issued for the purpose of collecting taxes travel\_document - Visas, entry permits, refugee documents, etc. voter\_id - Identification issued for the purpose of voting Possible values: birth\_certificate, drivers\_license, immigration\_number, military\_id, other, passport, personal\_identification, ration\_card, ssn, student\_id, tax\_id, travel\_document, voter\_id

**watchlist\_screening\_hits->data->documents->data->number** (string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**watchlist\_screening\_hits->data->locations** (\[object\])  
Locations associated with the watchlist hit

**watchlist\_screening\_hits->data->locations->analysis** (object)  
Summary object reflecting the match result of the associated data

**watchlist\_screening\_hits->data->locations->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->data->locations->data** (object)  
Location information for the associated individual watchlist hit

**watchlist\_screening\_hits->data->locations->data->full** (string)  
The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address.

**watchlist\_screening\_hits->data->locations->data->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**watchlist\_screening\_hits->data->names** (\[object\])  
Names associated with the watchlist hit

**watchlist\_screening\_hits->data->names->analysis** (object)  
Summary object reflecting the match result of the associated data

**watchlist\_screening\_hits->data->names->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**watchlist\_screening\_hits->data->names->data** (object)  
Name information for the associated individual watchlist hit

**watchlist\_screening\_hits->data->names->data->full** (string)  
The full name of the individual, including all parts.

**watchlist\_screening\_hits->data->names->data->is\_primary** (boolean)  
Primary names are those most commonly used to refer to this person. Only one name will ever be marked as primary.

**watchlist\_screening\_hits->data->names->data->weak\_alias\_determination** (string)  
Names that are explicitly marked as low quality either by their source list, or by plaid by a series of additional checks done by Plaid. Plaid does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be none. Possible values: none, source, plaid

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "watchlist_screening_hits": [
    {
      "id": "scrhit_52xR9LKo77r1Np",
      "review_status": "pending_review",
      "first_active": "2020-07-24T03:26:02Z",
      "inactive_since": "2020-07-24T03:26:02Z",
      "historical_since": "2020-07-24T03:26:02Z",
      "list_code": "US_SDN",
      "plaid_uid": "uid_3NggckTimGSJHS",
      "source_uid": "26192ABC",
      "analysis": {
        "dates_of_birth": "match",
        "documents": "match",
        "locations": "match",
        "names": "match",
        "search_terms_version": 1
      },
      "data": {
        "dates_of_birth": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "beginning": "1990-05-29",
              "ending": "1990-05-29"
            }
          }
        ],
        "documents": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "type": "passport",
              "number": "C31195855"
            }
          }
        ],
        "locations": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "full": "Florida, US",
              "country": "US"
            }
          }
        ],
        "names": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "full": "Aleksey Potemkin",
              "is_primary": false,
              "weak_alias_determination": "none"
            }
          }
        ]
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/program/get 

#### Get individual watchlist screening program 

Get an individual watchlist screening program

#### Request fields 

**watchlist\_program\_id** (required, string)  
ID of the associated program.

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

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

```javascript
const request: WatchlistScreeningIndividualProgramGetRequest = {
  watchlist_program_id: 'prg_2eRPsDnL66rZ7H',
};


try {
  const response = await client.watchlistScreeningIndividualProgramGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated program.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**is\_rescanning\_enabled** (boolean)  
Indicator specifying whether the program is enabled and will perform daily rescans.

**lists\_enabled** (\[string\])  
Watchlists enabled for the associated program Possible values: AU\_CON, CA\_CON, EU\_CON, IZ\_CIA, IZ\_IPL, IZ\_PEP, IZ\_UNC, IZ\_WBK, UK\_HMC, US\_DPL, US\_DTC, US\_FBI, US\_FSE, US\_ISN, US\_MBS, US\_PLC, US\_SAM, US\_SDN, US\_SSI, SG\_SOF, TR\_TWL, TR\_DFD, TR\_FOR, TR\_WMD, TR\_CMB

**name** (string)  
A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants".

**name\_sensitivity** (string)  
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: coarse, balanced, strict, exact

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**is\_archived** (boolean)  
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "prg_2eRPsDnL66rZ7H",
  "created_at": "2020-07-24T03:26:02Z",
  "is_rescanning_enabled": true,
  "lists_enabled": [
    "US_SDN"
  ],
  "name": "Sample Program",
  "name_sensitivity": "balanced",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "is_archived": false,
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/individual/program/list 

#### List individual watchlist screening programs 

List all individual watchlist screening programs

#### Request fields 

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

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

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
try {
  const response = await client.watchlistScreeningIndividualProgramList({});
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**watchlist\_programs** (\[object\])  
List of individual watchlist screening programs

**watchlist\_programs->id** (string)  
ID of the associated program.

**watchlist\_programs->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_programs->is\_rescanning\_enabled** (boolean)  
Indicator specifying whether the program is enabled and will perform daily rescans.

**watchlist\_programs->lists\_enabled** (\[string\])  
Watchlists enabled for the associated program Possible values: AU\_CON, CA\_CON, EU\_CON, IZ\_CIA, IZ\_IPL, IZ\_PEP, IZ\_UNC, IZ\_WBK, UK\_HMC, US\_DPL, US\_DTC, US\_FBI, US\_FSE, US\_ISN, US\_MBS, US\_PLC, US\_SAM, US\_SDN, US\_SSI, SG\_SOF, TR\_TWL, TR\_DFD, TR\_FOR, TR\_WMD, TR\_CMB

**watchlist\_programs->name** (string)  
A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants".

**watchlist\_programs->name\_sensitivity** (string)  
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: coarse, balanced, strict, exact

**watchlist\_programs->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**watchlist\_programs->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**watchlist\_programs->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**watchlist\_programs->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**watchlist\_programs->is\_archived** (boolean)  
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "watchlist_programs": [
    {
      "id": "prg_2eRPsDnL66rZ7H",
      "created_at": "2020-07-24T03:26:02Z",
      "is_rescanning_enabled": true,
      "lists_enabled": [
        "US_SDN"
      ],
      "name": "Sample Program",
      "name_sensitivity": "balanced",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      },
      "is_archived": false
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/create 

#### Create a watchlist screening for an entity 

Create a new entity watchlist screening to check your customer against watchlists defined in the associated entity watchlist program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

#### Request fields 

**search\_terms** (required, object)  
Search inputs for creating an entity watchlist screening

**search\_terms->entity\_watchlist\_program\_id** (required, string)  
ID of the associated entity program.

**search\_terms->legal\_name** (required, string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->document\_number** (string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**search\_terms->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->phone\_number** (string)  
A phone number in E.164 format.

**search\_terms->url** (string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

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

```javascript
const request: WatchlistScreeningEntityCreateRequest = {
  search_terms: {
    entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H',
    legal_name: 'Example Screening Entity',
    document_number: 'C31195855',
    email_address: 'user@example.com',
    country: 'US',
    phone_number: '+14025671234',
    url: 'https://example.com',
  },
  client_user_id: 'example-client-user-id-123',
};


try {
  const response = await client.watchlistScreeningEntityCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated entity screening.

**search\_terms** (object)  
Search terms associated with an entity used for searching against watchlists

**search\_terms->entity\_watchlist\_program\_id** (string)  
ID of the associated entity program.

**search\_terms->legal\_name** (string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->phone\_number** (nullable, string)  
A phone number in E.164 format.

**search\_terms->url** (nullable, string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "entscr_52xR9LKo77r1Np",
  "search_terms": {
    "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
    "legal_name": "Al-Qaida",
    "document_number": "C31195855",
    "email_address": "user@example.com",
    "country": "US",
    "phone_number": "+14025671234",
    "url": "https://example.com",
    "version": 1
  },
  "assignee": "54350110fedcbaf01234ffee",
  "status": "cleared",
  "client_user_id": "your-db-id-3b24110",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/get 

#### Get an entity screening 

Retrieve an entity watchlist screening.

#### Request fields 

**entity\_watchlist\_screening\_id** (required, string)  
ID of the associated entity screening.

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

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

```javascript
const request: WatchlistScreeningEntityGetRequest = {
  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningEntityGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated entity screening.

**search\_terms** (object)  
Search terms associated with an entity used for searching against watchlists

**search\_terms->entity\_watchlist\_program\_id** (string)  
ID of the associated entity program.

**search\_terms->legal\_name** (string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->phone\_number** (nullable, string)  
A phone number in E.164 format.

**search\_terms->url** (nullable, string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "entscr_52xR9LKo77r1Np",
  "search_terms": {
    "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
    "legal_name": "Al-Qaida",
    "document_number": "C31195855",
    "email_address": "user@example.com",
    "country": "US",
    "phone_number": "+14025671234",
    "url": "https://example.com",
    "version": 1
  },
  "assignee": "54350110fedcbaf01234ffee",
  "status": "cleared",
  "client_user_id": "your-db-id-3b24110",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/list 

#### List entity watchlist screenings 

List all entity screenings.

#### Request fields 

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

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

**entity\_watchlist\_program\_id** (required, string)  
ID of the associated entity program.

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**assignee** (string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningEntityListRequest = {
  entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H',
};


try {
  const response = await client.watchlistScreeningEntityList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**entity\_watchlist\_screenings** (\[object\])  
List of entity watchlist screening

**entity\_watchlist\_screenings->id** (string)  
ID of the associated entity screening.

**entity\_watchlist\_screenings->search\_terms** (object)  
Search terms associated with an entity used for searching against watchlists

**entity\_watchlist\_screenings->search\_terms->entity\_watchlist\_program\_id** (string)  
ID of the associated entity program.

**entity\_watchlist\_screenings->search\_terms->legal\_name** (string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**entity\_watchlist\_screenings->search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**entity\_watchlist\_screenings->search\_terms->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**entity\_watchlist\_screenings->search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**entity\_watchlist\_screenings->search\_terms->phone\_number** (nullable, string)  
A phone number in E.164 format.

**entity\_watchlist\_screenings->search\_terms->url** (nullable, string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**entity\_watchlist\_screenings->search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**entity\_watchlist\_screenings->assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**entity\_watchlist\_screenings->status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**entity\_watchlist\_screenings->client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**entity\_watchlist\_screenings->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**entity\_watchlist\_screenings->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**entity\_watchlist\_screenings->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**entity\_watchlist\_screenings->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "entity_watchlist_screenings": [
    {
      "id": "entscr_52xR9LKo77r1Np",
      "search_terms": {
        "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
        "legal_name": "Al-Qaida",
        "document_number": "C31195855",
        "email_address": "user@example.com",
        "country": "US",
        "phone_number": "+14025671234",
        "url": "https://example.com",
        "version": 1
      },
      "assignee": "54350110fedcbaf01234ffee",
      "status": "cleared",
      "client_user_id": "your-db-id-3b24110",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/update 

#### Update an entity screening 

Update an entity watchlist screening.

#### Request fields 

**entity\_watchlist\_screening\_id** (required, string)  
ID of the associated entity screening.

**search\_terms** (object)  
Search terms for editing an entity watchlist screening

**search\_terms->entity\_watchlist\_program\_id** (required, string)  
ID of the associated entity program.

**search\_terms->legal\_name** (string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->document\_number** (string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**search\_terms->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->phone\_number** (string)  
A phone number in E.164 format.

**search\_terms->url** (string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**assignee** (string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

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

**reset\_fields** (\[string\])  
A list of fields to reset back to null Possible values: assignee

```javascript
const request: WatchlistScreeningEntityUpdateRequest = {
  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
  status: 'cleared',
};


try {
  const response = await client.watchlistScreeningEntityUpdate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated entity screening.

**search\_terms** (object)  
Search terms associated with an entity used for searching against watchlists

**search\_terms->entity\_watchlist\_program\_id** (string)  
ID of the associated entity program.

**search\_terms->legal\_name** (string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**search\_terms->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**search\_terms->phone\_number** (nullable, string)  
A phone number in E.164 format.

**search\_terms->url** (nullable, string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "entscr_52xR9LKo77r1Np",
  "search_terms": {
    "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
    "legal_name": "Al-Qaida",
    "document_number": "C31195855",
    "email_address": "user@example.com",
    "country": "US",
    "phone_number": "+14025671234",
    "url": "https://example.com",
    "version": 1
  },
  "assignee": "54350110fedcbaf01234ffee",
  "status": "cleared",
  "client_user_id": "your-db-id-3b24110",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/history/list 

#### List history for entity watchlist screenings 

List all changes to the entity watchlist screening in reverse-chronological order. If the watchlist screening has not been edited, no history will be returned.

#### Request fields 

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

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

**entity\_watchlist\_screening\_id** (required, string)  
ID of the associated entity screening.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningEntityHistoryListRequest = {
  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningEntityHistoryList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**entity\_watchlist\_screenings** (\[object\])  
List of entity watchlist screening

**entity\_watchlist\_screenings->id** (string)  
ID of the associated entity screening.

**entity\_watchlist\_screenings->search\_terms** (object)  
Search terms associated with an entity used for searching against watchlists

**entity\_watchlist\_screenings->search\_terms->entity\_watchlist\_program\_id** (string)  
ID of the associated entity program.

**entity\_watchlist\_screenings->search\_terms->legal\_name** (string)  
The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.

**entity\_watchlist\_screenings->search\_terms->document\_number** (nullable, string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**entity\_watchlist\_screenings->search\_terms->email\_address** (nullable, string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**entity\_watchlist\_screenings->search\_terms->country** (nullable, string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**entity\_watchlist\_screenings->search\_terms->phone\_number** (nullable, string)  
A phone number in E.164 format.

**entity\_watchlist\_screenings->search\_terms->url** (nullable, string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**entity\_watchlist\_screenings->search\_terms->version** (integer)  
The current version of the search terms. Starts at 1 and increments with each edit to search\_terms.

**entity\_watchlist\_screenings->assignee** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**entity\_watchlist\_screenings->status** (string)  
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: rejected, pending\_review, cleared

**entity\_watchlist\_screenings->client\_user\_id** (nullable, string)  
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client\_user\_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**entity\_watchlist\_screenings->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**entity\_watchlist\_screenings->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**entity\_watchlist\_screenings->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**entity\_watchlist\_screenings->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "entity_watchlist_screenings": [
    {
      "id": "entscr_52xR9LKo77r1Np",
      "search_terms": {
        "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
        "legal_name": "Al-Qaida",
        "document_number": "C31195855",
        "email_address": "user@example.com",
        "country": "US",
        "phone_number": "+14025671234",
        "url": "https://example.com",
        "version": 1
      },
      "assignee": "54350110fedcbaf01234ffee",
      "status": "cleared",
      "client_user_id": "your-db-id-3b24110",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/review/create 

#### Create a review for an entity watchlist screening 

Create a review for an entity watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid.

#### Request fields 

**confirmed\_hits** (required, \[string\])  
Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

**dismissed\_hits** (required, \[string\])  
Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

**comment** (string)  
A comment submitted by a team member as part of reviewing a watchlist screening.

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

**entity\_watchlist\_screening\_id** (required, string)  
ID of the associated entity screening.

```javascript
const request: WatchlistScreeningEntityReviewCreateRequest = {
  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningEntityReviewCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated entity review.

**confirmed\_hits** (\[string\])  
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

**dismissed\_hits** (\[string\])  
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

**comment** (nullable, string)  
A comment submitted by a team member as part of reviewing a watchlist screening.

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "entrev_aCLNRxK3UVzn2r",
  "confirmed_hits": [
    "enthit_52xR9LKo77r1Np"
  ],
  "dismissed_hits": [
    "enthit_52xR9LKo77r1Np"
  ],
  "comment": "These look like legitimate matches, rejecting the customer.",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/review/list 

#### List reviews for entity watchlist screenings 

List all reviews for a particular entity watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid.

#### Request fields 

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

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

**entity\_watchlist\_screening\_id** (required, string)  
ID of the associated entity screening.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningEntityReviewListRequest = {
  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningEntityReviewList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**entity\_watchlist\_screening\_reviews** (\[object\])  
List of entity watchlist screening reviews

**entity\_watchlist\_screening\_reviews->id** (string)  
ID of the associated entity review.

**entity\_watchlist\_screening\_reviews->confirmed\_hits** (\[string\])  
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

**entity\_watchlist\_screening\_reviews->dismissed\_hits** (\[string\])  
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

**entity\_watchlist\_screening\_reviews->comment** (nullable, string)  
A comment submitted by a team member as part of reviewing a watchlist screening.

**entity\_watchlist\_screening\_reviews->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**entity\_watchlist\_screening\_reviews->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**entity\_watchlist\_screening\_reviews->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**entity\_watchlist\_screening\_reviews->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "entity_watchlist_screening_reviews": [
    {
      "id": "entrev_aCLNRxK3UVzn2r",
      "confirmed_hits": [
        "enthit_52xR9LKo77r1Np"
      ],
      "dismissed_hits": [
        "enthit_52xR9LKo77r1Np"
      ],
      "comment": "These look like legitimate matches, rejecting the customer.",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/hit/list 

#### List hits for entity watchlist screenings 

List all hits for the entity watchlist screening.

#### Request fields 

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

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

**entity\_watchlist\_screening\_id** (required, string)  
ID of the associated entity screening.

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
const request: WatchlistScreeningEntityHitListRequest = {
  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
};


try {
  const response = await client.watchlistScreeningEntityHitList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**entity\_watchlist\_screening\_hits** (\[object\])  
List of entity watchlist screening hits

**entity\_watchlist\_screening\_hits->id** (string)  
ID of the associated entity screening hit.

**entity\_watchlist\_screening\_hits->review\_status** (string)  
The current state of review. All watchlist screening hits begin in a pending\_review state but can be changed by creating a review. When a hit is in the pending\_review state, it will always show the latest version of the watchlist data Plaid has available and be compared against the latest customer information saved in the watchlist screening. Once a hit has been marked as confirmed or dismissed it will no longer be updated so that the state is as it was when the review was first conducted. Possible values: confirmed, pending\_review, dismissed

**entity\_watchlist\_screening\_hits->first\_active** (string)  
An ISO8601 formatted timestamp. Format: date-time

**entity\_watchlist\_screening\_hits->inactive\_since** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**entity\_watchlist\_screening\_hits->historical\_since** (nullable, string)  
An ISO8601 formatted timestamp. Format: date-time

**entity\_watchlist\_screening\_hits->list\_code** (string)  
Shorthand identifier for a specific screening list for entities. AU\_CON: Australia Department of Foreign Affairs and Trade Consolidated List CA\_CON: Government of Canada Consolidated List of Sanctions EU\_CON: European External Action Service Consolidated List IZ\_SOE: State Owned Enterprise List IZ\_UNC: United Nations Consolidated Sanctions IZ\_WBK: World Bank Listing of Ineligible Firms and Individuals US\_CAP: US OFAC Correspondent Account or Payable-Through Account Sanctions US\_FSE: US OFAC Foreign Sanctions Evaders US\_MBS: US Non-SDN Menu-Based Sanctions US\_SDN: US Specially Designated Nationals List US\_SSI: US OFAC Sectoral Sanctions Identifications US\_CMC: US OFAC Non-SDN Chinese Military-Industrial Complex List US\_UVL: Bureau of Industry and Security Unverified List US\_SAM: US System for Award Management Exclusion List US\_TEL: US Terrorist Exclusion List UK\_HMC: UK HM Treasury Consolidated List Possible values: CA\_CON, EU\_CON, IZ\_SOE, IZ\_UNC, IZ\_WBK, US\_CAP, US\_FSE, US\_MBS, US\_SDN, US\_SSI, US\_CMC, US\_UVL, US\_SAM, US\_TEL, AU\_CON, UK\_HMC

**entity\_watchlist\_screening\_hits->plaid\_uid** (string)  
A universal identifier for a watchlist individual that is stable across searches and updates.

**entity\_watchlist\_screening\_hits->source\_uid** (nullable, string)  
The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

**entity\_watchlist\_screening\_hits->analysis** (object)  
Analysis information describing why a screening hit matched the provided entity information

**entity\_watchlist\_screening\_hits->analysis->documents** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->analysis->email\_addresses** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->analysis->locations** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->analysis->names** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->analysis->phone\_numbers** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->analysis->urls** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->analysis->search\_terms\_version** (integer)  
The version of the entity screening's search\_terms that were compared when the entity screening hit was added. entity screening hits are immutable once they have been reviewed. If changes are detected due to updates to the entity screening's search\_terms, the associated entity program, or the list's source data prior to review, the entity screening hit will be updated to reflect those changes.

**entity\_watchlist\_screening\_hits->data** (object)  
Information associated with the entity watchlist hit

**entity\_watchlist\_screening\_hits->data->documents** (\[object\])  
Documents associated with the watchlist hit

**entity\_watchlist\_screening\_hits->data->documents->analysis** (object)  
Summary object reflecting the match result of the associated data

**entity\_watchlist\_screening\_hits->data->documents->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->data->documents->data** (object)  
An official document, usually issued by a governing body or institution, with an associated identifier.

**entity\_watchlist\_screening\_hits->data->documents->data->type** (string)  
The kind of official document represented by this object. bik - Russian bank code business\_number - A number that uniquely identifies the business within a category of businesses imo - Number assigned to the entity by the International Maritime Organization other - Any document not covered by other categories swift - Number identifying a bank and branch. tax\_id - Identification issued for the purpose of collecting taxes Possible values: bik, business\_number, imo, other, swift, tax\_id

**entity\_watchlist\_screening\_hits->data->documents->data->number** (string)  
The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.

**entity\_watchlist\_screening\_hits->data->email\_addresses** (\[object\])  
Email addresses associated with the watchlist hit

**entity\_watchlist\_screening\_hits->data->email\_addresses->analysis** (object)  
Summary object reflecting the match result of the associated data

**entity\_watchlist\_screening\_hits->data->email\_addresses->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->data->email\_addresses->data** (object)  
Email address information for the associated entity watchlist hit

**entity\_watchlist\_screening\_hits->data->email\_addresses->data->email\_address** (string)  
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696. Format: email

**entity\_watchlist\_screening\_hits->data->locations** (\[object\])  
Locations associated with the watchlist hit

**entity\_watchlist\_screening\_hits->data->locations->analysis** (object)  
Summary object reflecting the match result of the associated data

**entity\_watchlist\_screening\_hits->data->locations->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->data->locations->data** (object)  
Location information for the associated individual watchlist hit

**entity\_watchlist\_screening\_hits->data->locations->data->full** (string)  
The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address.

**entity\_watchlist\_screening\_hits->data->locations->data->country** (string)  
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

**entity\_watchlist\_screening\_hits->data->names** (\[object\])  
Names associated with the watchlist hit

**entity\_watchlist\_screening\_hits->data->names->analysis** (object)  
Summary object reflecting the match result of the associated data

**entity\_watchlist\_screening\_hits->data->names->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->data->names->data** (object)  
Name information for the associated entity watchlist hit

**entity\_watchlist\_screening\_hits->data->names->data->full** (string)  
The full name of the entity.

**entity\_watchlist\_screening\_hits->data->names->data->is\_primary** (boolean)  
Primary names are those most commonly used to refer to this entity. Only one name will ever be marked as primary.

**entity\_watchlist\_screening\_hits->data->names->data->weak\_alias\_determination** (string)  
Names that are explicitly marked as low quality either by their source list, or by plaid by a series of additional checks done by Plaid. Plaid does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be none. Possible values: none, source, plaid

**entity\_watchlist\_screening\_hits->data->phone\_numbers** (\[object\])  
Phone numbers associated with the watchlist hit

**entity\_watchlist\_screening\_hits->data->phone\_numbers->analysis** (object)  
Summary object reflecting the match result of the associated data

**entity\_watchlist\_screening\_hits->data->phone\_numbers->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->data->phone\_numbers->data** (object)  
Phone number information associated with the entity screening hit

**entity\_watchlist\_screening\_hits->data->phone\_numbers->data->type** (string)  
An enum indicating whether a phone number is a phone line or a fax line. Possible values: phone, fax

**entity\_watchlist\_screening\_hits->data->phone\_numbers->data->phone\_number** (string)  
A phone number in E.164 format.

**entity\_watchlist\_screening\_hits->data->urls** (\[object\])  
URLs associated with the watchlist hit

**entity\_watchlist\_screening\_hits->data->urls->analysis** (object)  
Summary object reflecting the match result of the associated data

**entity\_watchlist\_screening\_hits->data->urls->analysis->summary** (string)  
An enum indicating the match type between data provided by user and data checked against an external data source. match indicates that the provided input data was a strong match against external data. partial\_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. no\_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. no\_data indicates that Plaid was unable to find external data to compare against the provided input data. no\_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: match, partial\_match, no\_match, no\_data, no\_input

**entity\_watchlist\_screening\_hits->data->urls->data** (object)  
URLs associated with the entity screening hit

**entity\_watchlist\_screening\_hits->data->urls->data->url** (string)  
An 'http' or 'https' URL (must begin with either of those). Format: uri

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "entity_watchlist_screening_hits": [
    {
      "id": "enthit_52xR9LKo77r1Np",
      "review_status": "pending_review",
      "first_active": "2020-07-24T03:26:02Z",
      "inactive_since": "2020-07-24T03:26:02Z",
      "historical_since": "2020-07-24T03:26:02Z",
      "list_code": "EU_CON",
      "plaid_uid": "uid_3NggckTimGSJHS",
      "source_uid": "26192ABC",
      "analysis": {
        "documents": "match",
        "email_addresses": "match",
        "locations": "match",
        "names": "match",
        "phone_numbers": "match",
        "urls": "match",
        "search_terms_version": 1
      },
      "data": {
        "documents": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "type": "swift",
              "number": "C31195855"
            }
          }
        ],
        "email_addresses": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "email_address": "user@example.com"
            }
          }
        ],
        "locations": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "full": "Florida, US",
              "country": "US"
            }
          }
        ],
        "names": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "full": "Al Qaida",
              "is_primary": false,
              "weak_alias_determination": "none"
            }
          }
        ],
        "phone_numbers": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "type": "phone",
              "phone_number": "+14025671234"
            }
          }
        ],
        "urls": [
          {
            "analysis": {
              "summary": "match"
            },
            "data": {
              "url": "https://example.com"
            }
          }
        ]
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/program/get 

#### Get entity watchlist screening program 

Get an entity watchlist screening program

#### Request fields 

**entity\_watchlist\_program\_id** (required, string)  
ID of the associated entity program.

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

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

```javascript
const request: WatchlistScreeningEntityProgramGetRequest = {
  entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H',
};


try {
  const response = await client.watchlistScreeningEntityProgramGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**id** (string)  
ID of the associated entity program.

**created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**is\_rescanning\_enabled** (boolean)  
Indicator specifying whether the program is enabled and will perform daily rescans.

**lists\_enabled** (\[string\])  
Watchlists enabled for the associated program Possible values: CA\_CON, EU\_CON, IZ\_SOE, IZ\_UNC, IZ\_WBK, US\_CAP, US\_FSE, US\_MBS, US\_SDN, US\_SSI, US\_CMC, US\_UVL, US\_SAM, US\_TEL, AU\_CON, UK\_HMC

**name** (string)  
A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants".

**name\_sensitivity** (string)  
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: coarse, balanced, strict, exact

**audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**is\_archived** (boolean)  
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "id": "entprg_2eRPsDnL66rZ7H",
  "created_at": "2020-07-24T03:26:02Z",
  "is_rescanning_enabled": true,
  "lists_enabled": [
    "EU_CON"
  ],
  "name": "Sample Program",
  "name_sensitivity": "balanced",
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "is_archived": false,
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /watchlist\_screening/entity/program/list 

#### List entity watchlist screening programs 

List all entity watchlist screening programs

#### Request fields 

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

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

**cursor** (string)  
An identifier that determines which page of results you receive.

```javascript
try {
  const response = await client.watchlistScreeningEntityProgramList({});
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**entity\_watchlist\_programs** (\[object\])  
List of entity watchlist screening programs

**entity\_watchlist\_programs->id** (string)  
ID of the associated entity program.

**entity\_watchlist\_programs->created\_at** (string)  
An ISO8601 formatted timestamp. Format: date-time

**entity\_watchlist\_programs->is\_rescanning\_enabled** (boolean)  
Indicator specifying whether the program is enabled and will perform daily rescans.

**entity\_watchlist\_programs->lists\_enabled** (\[string\])  
Watchlists enabled for the associated program Possible values: CA\_CON, EU\_CON, IZ\_SOE, IZ\_UNC, IZ\_WBK, US\_CAP, US\_FSE, US\_MBS, US\_SDN, US\_SSI, US\_CMC, US\_UVL, US\_SAM, US\_TEL, AU\_CON, UK\_HMC

**entity\_watchlist\_programs->name** (string)  
A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants".

**entity\_watchlist\_programs->name\_sensitivity** (string)  
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: coarse, balanced, strict, exact

**entity\_watchlist\_programs->audit\_trail** (object)  
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

**entity\_watchlist\_programs->audit\_trail->source** (string)  
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: dashboard, link, api, system

**entity\_watchlist\_programs->audit\_trail->dashboard\_user\_id** (nullable, string)  
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard\_user/get.

**entity\_watchlist\_programs->audit\_trail->timestamp** (string)  
An ISO8601 formatted timestamp. Format: date-time

**entity\_watchlist\_programs->is\_archived** (boolean)  
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

**next\_cursor** (nullable, string)  
An identifier that determines which page of results you receive.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "entity_watchlist_programs": [
    {
      "id": "entprg_2eRPsDnL66rZ7H",
      "created_at": "2020-07-24T03:26:02Z",
      "is_rescanning_enabled": true,
      "lists_enabled": [
        "EU_CON"
      ],
      "name": "Sample Program",
      "name_sensitivity": "balanced",
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      },
      "is_archived": false
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

### Webhooks 

\=\*=\*=\*=

#### SCREENING: STATUS\_UPDATED 

Fired when an individual screening status has changed, which can occur manually via the dashboard or during ongoing monitoring.

#### Properties 

**webhook\_type** (string)  
SCREENING

**webhook\_code** (string)  
STATUS\_UPDATED

**screening\_id** (string)  
The ID of the associated screening.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "SCREENING",
  "webhook_code": "STATUS_UPDATED",
  "screening_id": "scr_52xR9LKo77r1Np",
  "environment": "production"
}
```

\=\*=\*=\*=

#### ENTITY\_SCREENING: STATUS\_UPDATED 

Fired when an entity screening status has changed, which can occur manually via the dashboard or during ongoing monitoring.

#### Properties 

**webhook\_type** (string)  
ENTITY\_SCREENING

**webhook\_code** (string)  
STATUS\_UPDATED

**entity\_screening\_id** (string)  
The ID of the associated entity screening.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "ENTITY_SCREENING",
  "webhook_code": "STATUS_UPDATED",
  "screening_id": "entscr_52xR9LKo77r1Np",
  "environment": "production"
}
```

---


# API - Payment Initiation (Europe) | Plaid Docs

Payment Initiation (UK and Europe) 
===================================

#### API reference for Payment Initiation endpoints and webhooks 

Make payment transfers from your app. Plaid supports both domestic payments denominated in local currencies and international payments, generally denominated in Euro. Domestic payments can be made in pound sterling (typically via the Faster Payments network), Euro (via SEPA Credit Transfer or SEPA Instant) and other local currencies (Polish Zloty, Danish Krone, Swedish Krona, Norwegian Krone), typically via local payment schemes.

For payments in the US, see [Transfer](https://plaid.com/docs/api/products/transfer/index.html.md) .

Looking for guidance on how to integrate using these endpoints? Check out the [Payment Initiation documentation](https://plaid.com/docs/payment-initiation/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) | Create a recipient |
| [/payment\_initiation/recipient/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientget) | Fetch recipient data |
| [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) | List all recipients |
| [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) | Create a payment |
| [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) | Fetch a payment |
| [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) | List all payments |
| [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | Refund a payment from a virtual account |
| [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) | Create a payment consent |
| [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) | Fetch a payment consent |
| [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) | Revoke a payment consent |
| [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) | Execute a payment using payment consent |

Users will be prompted to authorise the payment once you [initialise Link](https://plaid.com/docs/link/index.html.md#initializing-link) . See [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for more information on how to obtain a payments `link_token`.

| See also |  |
| --- | --- |
| [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) | Simulate a payment in Sandbox |
| [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) | Create a virtual account |
| [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) | Fetch a virtual account |
| [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) | List all virtual accounts |
| [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) | Execute a transaction |
| [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) | Fetch a transaction |
| [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) | List all transactions |
| [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) | The status of a transaction has changed |

| Webhooks |  |
| --- | --- |
| [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) | The status of a payment has changed |
| [CONSENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#consent_status_update) | The status of a consent has changed |

### Endpoints 

\=\*=\*=\*=

#### /payment\_initiation/recipient/create 

#### Create payment recipient 

Create a payment recipient for payment initiation. The recipient must be in Europe, within a country that is a member of the Single Euro Payment Area (SEPA) or a non-Eurozone country [supported](https://plaid.com/global) by Plaid. For a standing order (recurring) payment, the recipient must be in the UK.  
It is recommended to use `bacs` in the UK and `iban` in EU.  
The endpoint is idempotent: if a developer has already made a request with the same payment details, Plaid will return the same `recipient_id`.

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

**name** (required, string)  
The name of the recipient. We recommend using strings of length 18 or less and avoid special characters to ensure compatibility with all institutions. Min length: 1

**iban** (string)  
The International Bank Account Number (IBAN) for the recipient. If BACS data is not provided, an IBAN is required. Min length: 15 Max length: 34

**bacs** (object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**address** (object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**address->street** (required, \[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**address->city** (required, string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**address->postal\_code** (required, string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**address->country** (required, string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

```javascript
// Using BACS, without IBAN or address
const request: PaymentInitiationRecipientCreateRequest = {
  name: 'John Doe',
  bacs: {
    account: '26207729',
    sort_code: '560029',
  },
};
try {
  const response = await plaidClient.paymentInitiationRecipientCreate(request);
  const recipientID = response.data.recipient_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**recipient\_id** (string)  
A unique ID identifying the recipient

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /payment\_initiation/recipient/get 

#### Get payment recipient 

Get details about a payment recipient you have previously created.

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

**recipient\_id** (required, string)  
The ID of the recipient

```javascript
const request: PaymentInitiationRecipientGetRequest = {
  recipient_id: recipientID,
};
try {
  const response = await plaidClient.paymentInitiationRecipientGet(request);
  const recipientID = response.data.recipient_id;
  const name = response.data.name;
  const iban = response.data.iban;
  const address = response.data.address;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**recipient\_id** (string)  
The ID of the recipient.

**name** (string)  
The name of the recipient.

**address** (nullable, object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**address->street** (\[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**address->city** (string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**address->postal\_code** (string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**address->country** (string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**iban** (nullable, string)  
The International Bank Account Number (IBAN) for the recipient.

**bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
  "name": "Wonder Wallet",
  "iban": "GB29NWBK60161331926819",
  "address": {
    "street": [
      "96 Guild Street",
      "9th Floor"
    ],
    "city": "London",
    "postal_code": "SE14 8JW",
    "country": "GB"
  },
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /payment\_initiation/recipient/list 

#### List payment recipients 

The [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) endpoint list the payment recipients that you have previously created.

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

**count** (integer)  
The maximum number of recipients to return. If count is not specified, a maximum of 100 recipients will be returned, beginning with the recipient at the cursor (if specified). Minimum: 1 Maximum: 100 Default: 100

**cursor** (string)  
A value representing the latest recipient to be included in the response. Set this from next\_cursor received from the previous /payment\_initiation/recipient/list request. If provided, the response will only contain that recipient and recipients created before it. If omitted, the response will contain recipients starting from the most recent, and in descending order by the created\_at time. Max length: 256

```javascript
try {
  const response = await plaidClient.paymentInitiationRecipientList({});
  const recipients = response.data.recipients;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**recipients** (\[object\])  
An array of payment recipients created for Payment Initiation

**recipients->recipient\_id** (string)  
The ID of the recipient.

**recipients->name** (string)  
The name of the recipient.

**recipients->address** (nullable, object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**recipients->address->street** (\[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**recipients->address->city** (string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**recipients->address->postal\_code** (string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**recipients->address->country** (string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**recipients->iban** (nullable, string)  
The International Bank Account Number (IBAN) for the recipient.

**recipients->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**recipients->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**recipients->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**next\_cursor** (string)  
The value that, when used as the optional cursor parameter to /payment\_initiation/recipient/list, will return the corresponding recipient as its first recipient. Max length: 256

```json
{
  "recipients": [
    {
      "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
      "name": "Wonder Wallet",
      "iban": "GB29NWBK60161331926819",
      "address": {
        "street": [
          "96 Guild Street",
          "9th Floor"
        ],
        "city": "London",
        "postal_code": "SE14 8JW",
        "country": "GB"
      }
    }
  ],
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /payment\_initiation/payment/create 

#### Create a payment 

After creating a payment recipient, you can use the [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) endpoint to create a payment to that recipient. Payments can be one-time or standing order (recurring) and can be denominated in either EUR, GBP or other chosen [currency](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-create-request-amount-currency) . If making domestic GBP-denominated payments, your recipient must have been created with BACS numbers. In general, EUR-denominated payments will be sent via SEPA Credit Transfer, GBP-denominated payments will be sent via the Faster Payments network and for non-Eurozone markets typically via the local payment scheme, but the payment network used will be determined by the institution. Payments sent via Faster Payments will typically arrive immediately, while payments sent via SEPA Credit Transfer or other local payment schemes will typically arrive in one business day.  
Standing orders (recurring payments) must be denominated in GBP and can only be sent to recipients in the UK. Once created, standing order payments cannot be modified or canceled via the API. An end user can cancel or modify a standing order directly on their banking application or website, or by contacting the bank. Standing orders will follow the payment rules of the underlying rails (Faster Payments in UK). Payments can be sent Monday to Friday, excluding bank holidays. If the pre-arranged date falls on a weekend or bank holiday, the payment is made on the next working day. It is not possible to guarantee the exact time the payment will reach the recipient’s account, although at least 90% of standing order payments are sent by 6am.  
In Limited Production, payments must be below 5 GBP or other chosen [currency](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-create-request-amount-currency) , and standing orders, variable recurring payments, and Virtual Accounts are not supported.

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

**recipient\_id** (required, string)  
The ID of the recipient the payment is for.

**reference** (required, string)  
A reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them). In order to track settlement via Payment Confirmation, each payment must have a unique reference. If the reference provided through the API is not unique, Plaid will adjust it. Some institutions may limit the reference to less than 18 characters. If necessary, Plaid will adjust the reference by truncating it to fit the institution's requirements. Both the originally provided and automatically adjusted references (if any) can be found in the reference and adjusted\_reference fields, respectively. Min length: 1 Max length: 18

**amount** (required, object)  
The amount and currency of a payment

**amount->currency** (required, string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**amount->value** (required, number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**schedule** (object)  
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.

**schedule->interval** (required, string)  
The frequency interval of the payment. Possible values: WEEKLY, MONTHLYMin length: 1

**schedule->interval\_execution\_day** (required, integer)  
The day of the interval on which to schedule the payment. If the payment interval is weekly, interval\_execution\_day should be an integer from 1 (Monday) to 7 (Sunday). If the payment interval is monthly, interval\_execution\_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.

**schedule->start\_date** (required, string)  
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval\_execution\_day on or after the start\_date. If the first interval\_execution\_day on or after the start date is also the same day that /payment\_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**schedule->end\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval\_execution\_day on or before the end\_date. If the only interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /payment\_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**schedule->adjusted\_start\_date** (string)  
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null. Format: date

**options** (object)  
Additional payment options

**options->request\_refund\_details** (boolean)  
When true, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment\_initiation/payment/get response.

**options->iban** (string)  
The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to send payments only from the specified bank account if provided. Min length: 15 Max length: 34

**options->bacs** (object)  
An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.

**options->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**options->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**options->scheme** (string)  
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA\_CREDIT\_TRANSFER for EU). Using unsupported values will result in a failed payment. LOCAL\_DEFAULT: The default payment scheme for the selected market and currency will be used. LOCAL\_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: null, LOCAL\_DEFAULT, LOCAL\_INSTANT, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

```javascript
const request: PaymentInitiationPaymentCreateRequest = {
  recipient_id: recipientID,
  reference: 'TestPayment',
  amount: {
    currency: 'GBP',
    value: 100.0,
  },
};
try {
  const response = await plaidClient.paymentInitiationPaymentCreate(request);
  const paymentID = response.data.payment_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**payment\_id** (string)  
A unique ID identifying the payment

**status** (string)  
For a payment returned by this endpoint, there is only one possible value: PAYMENT\_STATUS\_INPUT\_NEEDED: The initial phase of the payment Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "status": "PAYMENT_STATUS_INPUT_NEEDED",
  "request_id": "4ciYVmesrySiUAB"
}
```

\=\*=\*=\*=

#### /payment\_initiation/payment/get 

#### Get payment details 

The [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) endpoint can be used to check the status of a payment, as well as to receive basic information such as recipient and payment amount. In the case of standing orders, the [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) endpoint will provide information about the status of the overall standing order itself; the API cannot be used to retrieve payment status for individual payments within a standing order.  
Polling for status updates in Production is highly discouraged. Repeatedly calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) to check a payment's status is unreliable and may trigger API rate limits. Only the `payment_status_update` webhook should be used to receive real-time status updates in Production.  
In the case of standing orders, the [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) endpoint will provide information about the status of the overall standing order itself; the API cannot be used to retrieve payment status for individual payments within a standing order.

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

**payment\_id** (required, string)  
The payment\_id returned from /payment\_initiation/payment/create.

```javascript
const request: PaymentInitiationPaymentGetRequest = {
  payment_id: paymentID,
};
try {
  const response = await plaidClient.paymentInitiationPaymentGet(request);
  const paymentID = response.data.payment_id;
  const paymentToken = response.data.payment_token;
  const reference = response.data.reference;
  const amount = response.data.amount;
  const status = response.data.status;
  const lastStatusUpdate = response.data.last_status_update;
  const paymentTokenExpirationTime =
    response.data.payment_token_expiration_time;
  const recipientID = response.data.recipient_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**payment\_id** (string)  
The ID of the payment. Like all Plaid identifiers, the payment\_id is case sensitive.

**amount** (object)  
The amount and currency of a payment

**amount->currency** (string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**amount->value** (number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

**recipient\_id** (string)  
The ID of the recipient

**reference** (string)  
A reference for the payment.

**adjusted\_reference** (nullable, string)  
The value of the reference sent to the bank after adjustment to pass bank validation rules.

**last\_status\_update** (string)  
The date and time of the last time the status was updated, in IS0 8601 format Format: date-time

**schedule** (nullable, object)  
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.

**schedule->interval** (string)  
The frequency interval of the payment. Possible values: WEEKLY, MONTHLYMin length: 1

**schedule->interval\_execution\_day** (integer)  
The day of the interval on which to schedule the payment. If the payment interval is weekly, interval\_execution\_day should be an integer from 1 (Monday) to 7 (Sunday). If the payment interval is monthly, interval\_execution\_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.

**schedule->start\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval\_execution\_day on or after the start\_date. If the first interval\_execution\_day on or after the start date is also the same day that /payment\_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**schedule->end\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval\_execution\_day on or before the end\_date. If the only interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /payment\_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**schedule->adjusted\_start\_date** (nullable, string)  
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null. Format: date

**refund\_details** (nullable, object)  
Details about external payment refund

**refund\_details->name** (string)  
The name of the account holder.

**refund\_details->iban** (nullable, string)  
The International Bank Account Number (IBAN) for the account.

**refund\_details->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**refund\_details->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**refund\_details->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**iban** (nullable, string)  
The International Bank Account Number (IBAN) for the sender, if specified in the /payment\_initiation/payment/create call.

**refund\_ids** (nullable, \[string\])  
Refund IDs associated with the payment.

**amount\_refunded** (nullable, object)  
The amount and currency of a payment

**amount\_refunded->currency** (string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**amount\_refunded->value** (number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Format: double Minimum: 0.01

**wallet\_id** (nullable, string)  
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.

**scheme** (nullable, string)  
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA\_CREDIT\_TRANSFER for EU). Using unsupported values will result in a failed payment. LOCAL\_DEFAULT: The default payment scheme for the selected market and currency will be used. LOCAL\_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: null, LOCAL\_DEFAULT, LOCAL\_INSTANT, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

**adjusted\_scheme** (nullable, string)  
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA\_CREDIT\_TRANSFER for EU). Using unsupported values will result in a failed payment. LOCAL\_DEFAULT: The default payment scheme for the selected market and currency will be used. LOCAL\_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: null, LOCAL\_DEFAULT, LOCAL\_INSTANT, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

**consent\_id** (nullable, string)  
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.

**transaction\_id** (nullable, string)  
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.

**end\_to\_end\_id** (nullable, string)  
A unique identifier assigned by Plaid to each payment for tracking and reconciliation purposes. Note: Not all banks handle end\_to\_end\_id consistently. To ensure accurate matching, clients should convert both the incoming end\_to\_end\_id and the one provided by Plaid to the same case (either lower or upper) before comparison. For virtual account payments, Plaid manages this field automatically.

**error** (nullable, 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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->error\_code\_reason** (nullable, 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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (nullable, 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.

**error->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.

**error->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.

**error->status** (nullable, 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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "payment_token": "payment-token-sandbox-c6a26505-42b4-46fe-8ecf-bf9edcafbebb",
  "reference": "Account Funding 99744",
  "amount": {
    "currency": "GBP",
    "value": 100
  },
  "status": "PAYMENT_STATUS_INPUT_NEEDED",
  "last_status_update": "2019-11-06T21:10:52Z",
  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
  "bacs": {
    "account": "31926819",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "sort_code": "601613"
  },
  "iban": null,
  "request_id": "aEAQmewMzlVa1k6"
}
```

\=\*=\*=\*=

#### /payment\_initiation/payment/list 

#### List payments 

The [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) endpoint can be used to retrieve all created payments. By default, the 10 most recent payments are returned. You can request more payments and paginate through the results using the optional `count` and `cursor` parameters.

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

**count** (integer)  
The maximum number of payments to return. If count is not specified, a maximum of 10 payments will be returned, beginning with the most recent payment before the cursor (if specified). Minimum: 1 Maximum: 200 Default: 10

**cursor** (string)  
A string in RFC 3339 format (i.e. "2019-12-06T22:35:49Z"). Only payments created before the cursor will be returned. Format: date-time

**consent\_id** (string)  
The consent ID. If specified, only payments, executed using this consent, will be returned.

```javascript
const request: PaymentInitiationPaymentListRequest = {
  count: 10,
  cursor: '2019-12-06T22:35:49Z',
};
try {
  const response = await plaidClient.paymentInitiationPaymentList(request);
  const payments = response.data.payments;
  const nextCursor = response.data.next_cursor;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**payments** (\[object\])  
An array of payments that have been created, associated with the given client\_id.

**payments->payment\_id** (string)  
The ID of the payment. Like all Plaid identifiers, the payment\_id is case sensitive.

**payments->amount** (object)  
The amount and currency of a payment

**payments->amount->currency** (string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**payments->amount->value** (number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**payments->status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

**payments->recipient\_id** (string)  
The ID of the recipient

**payments->reference** (string)  
A reference for the payment.

**payments->adjusted\_reference** (nullable, string)  
The value of the reference sent to the bank after adjustment to pass bank validation rules.

**payments->last\_status\_update** (string)  
The date and time of the last time the status was updated, in IS0 8601 format Format: date-time

**payments->schedule** (nullable, object)  
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.

**payments->schedule->interval** (string)  
The frequency interval of the payment. Possible values: WEEKLY, MONTHLYMin length: 1

**payments->schedule->interval\_execution\_day** (integer)  
The day of the interval on which to schedule the payment. If the payment interval is weekly, interval\_execution\_day should be an integer from 1 (Monday) to 7 (Sunday). If the payment interval is monthly, interval\_execution\_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.

**payments->schedule->start\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval\_execution\_day on or after the start\_date. If the first interval\_execution\_day on or after the start date is also the same day that /payment\_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**payments->schedule->end\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval\_execution\_day on or before the end\_date. If the only interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /payment\_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**payments->schedule->adjusted\_start\_date** (nullable, string)  
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null. Format: date

**payments->refund\_details** (nullable, object)  
Details about external payment refund

**payments->refund\_details->name** (string)  
The name of the account holder.

**payments->refund\_details->iban** (nullable, string)  
The International Bank Account Number (IBAN) for the account.

**payments->refund\_details->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**payments->refund\_details->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**payments->refund\_details->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**payments->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**payments->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**payments->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**payments->iban** (nullable, string)  
The International Bank Account Number (IBAN) for the sender, if specified in the /payment\_initiation/payment/create call.

**payments->refund\_ids** (nullable, \[string\])  
Refund IDs associated with the payment.

**payments->amount\_refunded** (nullable, object)  
The amount and currency of a payment

**payments->amount\_refunded->currency** (string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**payments->amount\_refunded->value** (number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Format: double Minimum: 0.01

**payments->wallet\_id** (nullable, string)  
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.

**payments->scheme** (nullable, string)  
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA\_CREDIT\_TRANSFER for EU). Using unsupported values will result in a failed payment. LOCAL\_DEFAULT: The default payment scheme for the selected market and currency will be used. LOCAL\_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: null, LOCAL\_DEFAULT, LOCAL\_INSTANT, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

**payments->adjusted\_scheme** (nullable, string)  
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA\_CREDIT\_TRANSFER for EU). Using unsupported values will result in a failed payment. LOCAL\_DEFAULT: The default payment scheme for the selected market and currency will be used. LOCAL\_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: null, LOCAL\_DEFAULT, LOCAL\_INSTANT, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

**payments->consent\_id** (nullable, string)  
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.

**payments->transaction\_id** (nullable, string)  
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.

**payments->end\_to\_end\_id** (nullable, string)  
A unique identifier assigned by Plaid to each payment for tracking and reconciliation purposes. Note: Not all banks handle end\_to\_end\_id consistently. To ensure accurate matching, clients should convert both the incoming end\_to\_end\_id and the one provided by Plaid to the same case (either lower or upper) before comparison. For virtual account payments, Plaid manages this field automatically.

**payments->error** (nullable, 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.

**payments->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**payments->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**payments->error->error\_code\_reason** (nullable, 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.

**payments->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**payments->error->display\_message** (nullable, 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.

**payments->error->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.

**payments->error->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.

**payments->error->status** (nullable, 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.

**payments->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**payments->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**next\_cursor** (nullable, string)  
The value that, when used as the optional cursor parameter to /payment\_initiation/payment/list, will return the next unreturned payment as its first payment. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "payments": [
    {
      "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
      "reference": "Account Funding 99744",
      "amount": {
        "currency": "GBP",
        "value": 100
      },
      "status": "PAYMENT_STATUS_INPUT_NEEDED",
      "last_status_update": "2019-11-06T21:10:52Z",
      "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
      "bacs": {
        "account": "31926819",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "sort_code": "601613"
      },
      "iban": null
    }
  ],
  "next_cursor": "2020-01-01T00:00:00Z",
  "request_id": "aEAQmewMzlVa1k6"
}
```

\=\*=\*=\*=

#### /payment\_initiation/payment/reverse 

#### Reverse an existing payment 

Reverse a settled payment from a Plaid virtual account.  
The original payment must be in a settled state to be refunded. To refund partially, specify the amount as part of the request. If the amount is not specified, the refund amount will be equal to all of the remaining payment amount that has not been refunded yet.  
The refund will go back to the source account that initiated the payment. The original payment must have been initiated to a Plaid virtual account so that this account can be used to initiate the refund.  
Providing counterparty information such as date of birth and address increases the likelihood of refund being successful without human intervention.

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

**payment\_id** (required, string)  
The ID of the payment to reverse

**idempotency\_key** (required, string)  
A random key provided by the client, per unique wallet transaction. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed. Max length: 128 Min length: 1

**reference** (required, string)  
A reference for the refund. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces. Max length: 18 Min length: 6

**amount** (object)  
The amount and currency of a payment

**amount->currency** (required, string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**amount->value** (required, number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Format: double Minimum: 0.01

**counterparty\_date\_of\_birth** (string)  
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format. Format: date

**counterparty\_address** (object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**counterparty\_address->street** (required, \[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**counterparty\_address->city** (required, string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**counterparty\_address->postal\_code** (required, string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**counterparty\_address->country** (required, string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

```javascript
const request: PaymentInitiationPaymentReverseRequest = {
  payment_id: paymentID,
  reference: 'Refund for purchase ABC123',
  idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912',
};
try {
  const response = await plaidClient.paymentInitiationPaymentReverse(request);
  const refundID = response.data.refund_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**refund\_id** (string)  
A unique ID identifying the refund

**status** (string)  
The status of the transaction. AUTHORISING: The transaction is being processed for validation and compliance. INITIATED: The transaction has been initiated and is currently being processed. EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. FAILED: The transaction failed to process successfully. This is a terminal status. BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "refund_id": "wallet-transaction-id-production-c5f8cd31-6cae-4cad-9b0d-f7c10be9cc4b",
  "request_id": "HtlKzBX0fMeF7mU",
  "status": "INITIATED"
}
```

\=\*=\*=\*=

#### /payment\_initiation/consent/create 

#### Create payment consent 

The [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) endpoint is used to create a payment consent, which can be used to initiate payments on behalf of the user. Payment consents are created with `UNAUTHORISED` status by default and must be authorised by the user before payments can be initiated.  
Consents can be limited in time and scope, and have constraints that describe limitations for payments.

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

**recipient\_id** (required, string)  
The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only.

**reference** (required, string)  
A reference for the payment consent. This must be an alphanumeric string with at most 18 characters and must not contain any special characters. Min length: 1 Max length: 18

**scopes** (deprecated, \[string\])  
An array of payment consent scopes. Min items: 1 Possible values: ME\_TO\_ME, EXTERNAL

**type** (string)  
Payment consent type. Defines possible use case for payments made with the given consent. SWEEPING: Allows moving money between accounts owned by the same user. COMMERCIAL: Allows initiating payments from the user's account to third parties. Possible values: SWEEPING, COMMERCIAL

**constraints** (required, object)  
Limitations that will be applied to payments initiated using the payment consent.

**constraints->valid\_date\_time** (object)  
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.

**constraints->valid\_date\_time->from** (string)  
The date and time from which the consent should be active, in ISO 8601 format. Format: date-time

**constraints->valid\_date\_time->to** (string)  
The date and time at which the consent expires, in ISO 8601 format. Format: date-time

**constraints->max\_payment\_amount** (required, object)  
Maximum amount of a single payment initiated using the payment consent.

**constraints->max\_payment\_amount->currency** (required, string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**constraints->max\_payment\_amount->value** (required, number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**constraints->periodic\_amounts** (required, \[object\])  
A list of amount limitations per period of time. Min items: 1

**constraints->periodic\_amounts->amount** (required, object)  
Maximum cumulative amount for all payments in the specified interval.

**constraints->periodic\_amounts->amount->currency** (required, string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**constraints->periodic\_amounts->amount->value** (required, number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**constraints->periodic\_amounts->interval** (required, string)  
Payment consent periodic interval. Possible values: DAY, WEEK, MONTH, YEAR

**constraints->periodic\_amounts->alignment** (required, string)  
Where the payment consent period should start. If the institution is Monzo, only CONSENT alignments are supported. CALENDAR: line up with a calendar. CONSENT: on the date of consent creation. Possible values: CALENDAR, CONSENT

**options** (deprecated, object)  
(Deprecated) Additional payment consent options. Please use payer\_details to specify the account.

**options->request\_refund\_details** (boolean)  
When true, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment\_initiation/payment/get response.

**options->iban** (string)  
The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to set up payment consent using only the specified bank account if provided. Min length: 15 Max length: 34

**options->bacs** (object)  
An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.

**options->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**options->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**payer\_details** (object)  
An object representing the payment consent payer details. Payer name and account numbers are required to lock the account to which the consent can be created.

**payer\_details->name** (required, string)  
The name of the payer as it appears in their bank account Min length: 1

**payer\_details->numbers** (required, object)  
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.

**payer\_details->numbers->bacs** (object)  
An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.

**payer\_details->numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**payer\_details->numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**payer\_details->numbers->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**payer\_details->address** (object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**payer\_details->address->street** (required, \[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**payer\_details->address->city** (required, string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**payer\_details->address->postal\_code** (required, string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**payer\_details->address->country** (required, string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**payer\_details->date\_of\_birth** (string)  
The payer's birthdate, in ISO 8601 (YYYY-MM-DD) format. Format: date

**payer\_details->phone\_numbers** (\[string\])  
The payer's phone numbers in E.164 format: +{countrycode}{number}

**payer\_details->emails** (\[string\])  
The payer's emails

```javascript
const request: PaymentInitiationConsentCreateRequest = {
  recipient_id: recipientID,
  reference: 'TestPaymentConsent',
  type: PaymentInitiationConsentType.Commercial,
  constraints: {
    valid_date_time: {
      to: '2024-12-31T23:59:59Z',
    },
    max_payment_amount: {
      currency: PaymentAmountCurrency.Gbp,
      value: 15,
    },
    periodic_amounts: [
      {
        amount: {
          currency: PaymentAmountCurrency.Gbp,
          value: 40,
        },
        alignment: PaymentConsentPeriodicAlignment.Calendar,
        interval: PaymentConsentPeriodicInterval.Month,
      },
    ],
  },
};


try {
  const response = await plaidClient.paymentInitiationConsentCreate(request);
  const consentID = response.data.consent_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**consent\_id** (string)  
A unique ID identifying the payment consent.

**status** (string)  
The status of the payment consent. UNAUTHORISED: Consent created, but requires user authorisation. REJECTED: Consent authorisation was rejected by the user and/or the bank. AUTHORISED: Consent is active and ready to be used. REVOKED: Consent has been revoked and can no longer be used. EXPIRED: Consent is no longer valid. Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "consent_id": "consent-id-production-feca8a7a-5491-4444-9999-f3062bb735d3",
  "status": "UNAUTHORISED",
  "request_id": "4ciYmmesdqSiUAB"
}
```

\=\*=\*=\*=

#### /payment\_initiation/consent/get 

#### Get payment consent 

The [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) endpoint can be used to check the status of a payment consent, as well as to receive basic information such as recipient and constraints.

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

**consent\_id** (required, string)  
The consent\_id returned from /payment\_initiation/consent/create.

```javascript
const request: PaymentInitiationConsentGetRequest = {
  consent_id: consentID,
};


try {
  const response = await plaidClient.paymentInitiationConsentGet(request);
  const consentID = response.data.consent_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**consent\_id** (string)  
The consent ID. Min length: 1

**status** (string)  
The status of the payment consent. UNAUTHORISED: Consent created, but requires user authorisation. REJECTED: Consent authorisation was rejected by the user and/or the bank. AUTHORISED: Consent is active and ready to be used. REVOKED: Consent has been revoked and can no longer be used. EXPIRED: Consent is no longer valid. Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED

**created\_at** (string)  
Consent creation timestamp, in ISO 8601 format. Format: date-time

**recipient\_id** (string)  
The ID of the recipient the payment consent is for. Min length: 1

**reference** (string)  
A reference for the payment consent.

**constraints** (object)  
Limitations that will be applied to payments initiated using the payment consent.

**constraints->valid\_date\_time** (nullable, object)  
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.

**constraints->valid\_date\_time->from** (nullable, string)  
The date and time from which the consent should be active, in ISO 8601 format. Format: date-time

**constraints->valid\_date\_time->to** (nullable, string)  
The date and time at which the consent expires, in ISO 8601 format. Format: date-time

**constraints->max\_payment\_amount** (object)  
Maximum amount of a single payment initiated using the payment consent.

**constraints->max\_payment\_amount->currency** (string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**constraints->max\_payment\_amount->value** (number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**constraints->periodic\_amounts** (\[object\])  
A list of amount limitations per period of time. Min items: 1

**constraints->periodic\_amounts->amount** (object)  
Maximum cumulative amount for all payments in the specified interval.

**constraints->periodic\_amounts->amount->currency** (string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**constraints->periodic\_amounts->amount->value** (number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**constraints->periodic\_amounts->interval** (string)  
Payment consent periodic interval. Possible values: DAY, WEEK, MONTH, YEAR

**constraints->periodic\_amounts->alignment** (string)  
Where the payment consent period should start. If the institution is Monzo, only CONSENT alignments are supported. CALENDAR: line up with a calendar. CONSENT: on the date of consent creation. Possible values: CALENDAR, CONSENT

**scopes** (deprecated, \[string\])  
Deprecated, use the 'type' field instead. Possible values: ME\_TO\_ME, EXTERNAL

**type** (string)  
Payment consent type. Defines possible use case for payments made with the given consent. SWEEPING: Allows moving money between accounts owned by the same user. COMMERCIAL: Allows initiating payments from the user's account to third parties. Possible values: SWEEPING, COMMERCIAL

**payer\_details** (nullable, object)  
Details about external payment refund

**payer\_details->name** (string)  
The name of the account holder.

**payer\_details->iban** (nullable, string)  
The International Bank Account Number (IBAN) for the account.

**payer\_details->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.

**payer\_details->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**payer\_details->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "request_id": "4ciYuuesdqSiUAB",
  "consent_id": "consent-id-production-feca8a7a-5491-4aef-9298-f3062bb735d3",
  "status": "AUTHORISED",
  "created_at": "2021-10-30T15:26:48Z",
  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
  "reference": "ref-00001",
  "constraints": {
    "valid_date_time": {
      "from": "2021-12-25T11:12:13Z",
      "to": "2022-12-31T15:26:48Z"
    },
    "max_payment_amount": {
      "currency": "GBP",
      "value": 100
    },
    "periodic_amounts": [
      {
        "amount": {
          "currency": "GBP",
          "value": 300
        },
        "interval": "WEEK",
        "alignment": "CALENDAR"
      }
    ]
  },
  "type": "SWEEPING"
}
```

\=\*=\*=\*=

#### /payment\_initiation/consent/revoke 

#### Revoke payment consent 

The [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) endpoint can be used to revoke the payment consent. Once the consent is revoked, it is not possible to initiate payments using it.

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

**consent\_id** (required, string)  
The consent ID.

```javascript
const request: PaymentInitiationConsentRevokeRequest = {
  consent_id: consentID,
};
try {
  const response = await plaidClient.paymentInitiationConsentRevoke(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "4ciYaaesdqSiUAB"
}
```

\=\*=\*=\*=

#### /payment\_initiation/consent/payment/execute 

#### Execute a single payment using consent 

The [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) endpoint can be used to execute payments using payment consent.

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

**consent\_id** (required, string)  
The consent ID.

**amount** (required, object)  
The amount and currency of a payment

**amount->currency** (required, string)  
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: GBP, EUR, PLN, SEK, DKK, NOKMin length: 3 Max length: 3

**amount->value** (required, number)  
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1. Format: double

**idempotency\_key** (required, string)  
A random key provided by the client, per unique consent payment. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a consent payment fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single payment is created. If the request was successfully processed, it will prevent any payment that uses the same idempotency key, and was received within 48 hours of the first request, from being processed. Max length: 128 Min length: 1

**reference** (string)  
A reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them). If not provided, Plaid will automatically fall back to the reference from consent. In order to track settlement via Payment Confirmation, each payment must have a unique reference. If the reference provided through the API is not unique, Plaid will adjust it. Some institutions may limit the reference to less than 18 characters. If necessary, Plaid will adjust the reference by truncating it to fit the institution's requirements. Both the originally provided and automatically adjusted references (if any) can be found in the reference and adjusted\_reference fields, respectively. Min length: 1 Max length: 18

**scope** (deprecated, string)  
Deprecated, payments will be executed within the type of the consent. A scope of the payment. Must be one of the scopes mentioned in the consent. Optional if the appropriate consent has only one scope defined, required otherwise. Possible values: ME\_TO\_ME, EXTERNAL

**processing\_mode** (string)  
Decides the mode under which the payment processing should be performed, using IMMEDIATE as default. IMMEDIATE: Will immediately execute the payment, waiting for a response from the ASPSP before returning the result of the payment initiation. This is ideal for user-present flows. ASYNC: Will accept a payment execution request and schedule it for processing, immediately returning the new payment\_id. Listen for webhooks to obtain real-time updates on the payment status. This is ideal for non user-present flows. Possible values: ASYNC, IMMEDIATE

```javascript
const request: PaymentInitiationConsentPaymentExecuteRequest = {
  consent_id: consentID,
  amount: {
    currency: PaymentAmountCurrency.Gbp,
    value: 7.99,
  },
  reference: 'Payment1',
  idempotency_key: idempotencyKey,
};
try {
  const response = await plaidClient.paymentInitiationConsentPaymentExecute(
    request,
  );
  const paymentID = response.data.payment_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**payment\_id** (string)  
A unique ID identifying the payment

**status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

**error** (nullable, 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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->error\_code\_reason** (nullable, 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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (nullable, 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.

**error->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.

**error->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.

**error->status** (nullable, 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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

```json
{
  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "request_id": "4ciYccesdqSiUAB",
  "status": "PAYMENT_STATUS_INITIATED"
}
```

### Webhooks 

Updates are sent to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a `webhook_type` of `PAYMENT_INITIATION`.

\=\*=\*=\*=

#### PAYMENT\_STATUS\_UPDATE 

Fired when the status of a payment has changed.

#### Properties 

**webhook\_type** (string)  
PAYMENT\_INITIATION

**webhook\_code** (string)  
PAYMENT\_STATUS\_UPDATE

**payment\_id** (string)  
The payment\_id for the payment being updated

**transaction\_id** (string)  
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.

**new\_payment\_status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

**old\_payment\_status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

**original\_reference** (string)  
The original value of the reference when creating the payment.

**adjusted\_reference** (string)  
The value of the reference sent to the bank after adjustment to pass bank validation rules.

**original\_start\_date** (string)  
The original value of the start\_date provided during the creation of a standing order. If the payment is not a standing order, this field will be null. Format: date

**adjusted\_start\_date** (string)  
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, or if the payment is not a standing order, this field will be null. Format: date

**timestamp** (string)  
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "PAYMENT_INITIATION",
  "webhook_code": "PAYMENT_STATUS_UPDATE",
  "payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
  "new_payment_status": "PAYMENT_STATUS_INITIATED",
  "old_payment_status": "PAYMENT_STATUS_PROCESSING",
  "original_reference": "Account Funding 99744",
  "adjusted_reference": "Account Funding 99",
  "original_start_date": "2017-09-14",
  "adjusted_start_date": "2017-09-15",
  "timestamp": "2017-09-14T14:42:19.350Z",
  "environment": "production"
}
```

\=\*=\*=\*=

#### CONSENT\_STATUS\_UPDATE 

Fired when the status of a payment consent has changed.

#### Properties 

**webhook\_type** (string)  
PAYMENT\_INITIATION

**webhook\_code** (string)  
CONSENT\_STATUS\_UPDATE

**consent\_id** (string)  
The id for the consent being updated

**old\_status** (string)  
The status of the payment consent. UNAUTHORISED: Consent created, but requires user authorisation. REJECTED: Consent authorisation was rejected by the user and/or the bank. AUTHORISED: Consent is active and ready to be used. REVOKED: Consent has been revoked and can no longer be used. EXPIRED: Consent is no longer valid. Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED

**new\_status** (string)  
The status of the payment consent. UNAUTHORISED: Consent created, but requires user authorisation. REJECTED: Consent authorisation was rejected by the user and/or the bank. AUTHORISED: Consent is active and ready to be used. REVOKED: Consent has been revoked and can no longer be used. EXPIRED: Consent is no longer valid. Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED

**timestamp** (string)  
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "PAYMENT_INITIATION",
  "webhook_code": "CONSENT_STATUS_UPDATE",
  "consent_id": "payment-consent-id-production-e7258765-69f9-46b1-9c67-d2800448e5ff",
  "old_status": "UNAUTHORISED",
  "new_status": "AUTHORISED",
  "timestamp": "2017-09-14T14:42:19.350Z",
  "environment": "production"
}
```

---


# API - Protect | Plaid Docs

Protect 
========

#### API reference for Protect endpoints 

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

| Endpoints |  |
| --- | --- |
| [/protect/event/send](https://plaid.com/docs/api/products/protect/index.html.md#protecteventsend) | Sends your backend event to Plaid Protect |
| [/protect/event/get](https://plaid.com/docs/api/products/protect/index.html.md#protecteventget) | Returns event details and trust index score metadata |
| [/protect/user/insights/get](https://plaid.com/docs/api/products/protect/index.html.md#protectuserinsightsget) | Returns the latest user event details and other metadata |

| Webhooks |  |
| --- | --- |
| [PROTECT\_USER\_EVENT](https://plaid.com/docs/api/products/protect/index.html.md#protect_user_event) | Sent when an event occurs for a user |

### Endpoints 

\=\*=\*=\*=

#### /protect/event/send 

#### Send a new event to enrich user data 

Send a new event to enrich user data and optionally get a Trust Index score for the event.

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

**timestamp** (string)  
Timestamp of the event. Might be the current moment or a time in the past. In ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**event** (required, object)  
Event data for Protect events.

**event->timestamp** (required, string)  
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**event->protect\_session\_id** (string)  
If present, contains the current Protect Session ID from the Plaid Pixel SDK.

**event->app\_visit** (object)  
This event type represents a user visiting the client application.

**event->user\_sign\_in** (object)  
This event type represents a user signing in to the application.

**event->user\_sign\_up** (object)  
This event type represents a user signing up for the application.

**protect\_session\_id** (string)  
Protect Session ID should be provided for any event correlated with a frontend user session started via the Protect SDK.

**request\_trust\_index** (boolean)  
Whether this event should be scored with Trust Index. The default is false.

```javascript
const request: ProtectEventSendRequest = {
    event: {
      user_sign_in: {},
      timestamp: '2025-05-14T14:42:19.350Z'
    },
    user: {
      client_user_id: 'user-abc'
    },
  };
  try {
    const response = await client.protectEventSend(request);
    const eventId = response.data.event_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**event\_id** (string)  
The id of the recorded event.

**trust\_index** (nullable, object)  
Represents a calculate Trust Index Score.

**trust\_index->score** (integer)  
The overall trust index score.

**trust\_index->model** (string)  
The versioned name of the Trust Index model used for scoring.

**trust\_index->subscores** (nullable, object)  
Contains sub-score metadata.

**trust\_index->subscores->device\_and\_connection** (nullable, object)  
Represents Trust Index Subscore.

**trust\_index->subscores->device\_and\_connection->score** (integer)  
The subscore score.

**trust\_index->subscores->bank\_account\_insights** (nullable, object)  
Represents Trust Index Subscore.

**trust\_index->subscores->bank\_account\_insights->score** (integer)  
The subscore score.

**fraud\_attributes** (nullable, object)  
Event fraud attributes as an arbitrary set of key-value pairs.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "event_id": "protect-event-2be8498f",
  "trust_index": {
    "score": 86,
    "model": "ti-pro-1.0",
    "subscores": {
      "device_and_connection": {
        "score": 87
      },
      "bank_account_insights": {
        "score": 85
      }
    },
    "fraud_attributes": {
      "num_distinct_names_on_accounts": 3,
      "identity_match_idv_bank_account": true,
      "idv_id_doc_passed": true
    }
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /protect/event/get 

#### Get information about a user event 

Get information about a user event including Trust Index score and fraud attributes.

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

**event\_id** (required, string)  
The event ID to retrieve information for.

```javascript
const request: ProtectEventGetRequest = {
  event_id: 'evt_abcdefghij1234567890'
};
  try {
  const response = await client.protectEventGet(request);
  const trustScore = response.data.trust_index.score;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**event\_id** (string)  
The event ID.

**timestamp** (string)  
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**trust\_index** (nullable, object)  
Represents a calculate Trust Index Score.

**trust\_index->score** (integer)  
The overall trust index score.

**trust\_index->model** (string)  
The versioned name of the Trust Index model used for scoring.

**trust\_index->subscores** (nullable, object)  
Contains sub-score metadata.

**trust\_index->subscores->device\_and\_connection** (nullable, object)  
Represents Trust Index Subscore.

**trust\_index->subscores->device\_and\_connection->score** (integer)  
The subscore score.

**trust\_index->subscores->bank\_account\_insights** (nullable, object)  
Represents Trust Index Subscore.

**trust\_index->subscores->bank\_account\_insights->score** (integer)  
The subscore score.

**fraud\_attributes** (nullable, object)  
Event fraud attributes as an arbitrary set of key-value pairs.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "event_id": "protect-event-2be8498f",
  "timestamp": "2020-07-24T03:26:02Z",
  "trust_index": {
    "score": 86,
    "model": "ti-pro-1.0",
    "subscores": {
      "device_and_connection": {
        "score": 87
      },
      "bank_account_insights": {
        "score": 85
      }
    }
  },
  "fraud_attributes": {
    "num_distinct_names_on_accounts": 3,
    "identity_match_idv_bank_account": true,
    "idv_id_doc_passed": true,
    "bank_accounts": [
      {
        "account_name": "Premium Checking",
        "account_type": "checking",
        "institution_name": "Huntington Credit Union",
        "account_age_days": 144,
        "num_distinct_owner_names": 3
      },
      {
        "account_name": "Credit ***8889",
        "account_type": "credit"
      }
    ]
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /protect/user/insights/get 

#### Get Protect user insights 

Use this endpoint to get basic information about a user as it relates to their fraud profile with Protect.

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

**user\_id** (string)  
The Plaid User ID. Either user\_id or client\_user\_id must be provided.

**client\_user\_id** (string)  
A unique ID representing the end user. Either user\_id or client\_user\_id must be provided.

```javascript
const request: ProtectUserInsightsGetRequest = {
  client_user_id: 'user-abc'
};
try {
  const response = await client.protectUserInsightsGet(request);
  const trustScore = response.data.latest_scored_event.trust_index.score;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**user\_id** (string)  
The Plaid User ID. If a client\_user\_id was provided in the request instead of a user\_id, a new user\_id will be generated if one doesn't already exist for that client\_user\_id.

**latest\_scored\_event** (nullable, object)  
The latest scored event for a user.

**latest\_scored\_event->event\_id** (string)  
The event ID.

**latest\_scored\_event->timestamp** (string)  
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**latest\_scored\_event->event\_type** (string)  
The type of event.

**latest\_scored\_event->trust\_index** (nullable, object)  
Represents a calculate Trust Index Score.

**latest\_scored\_event->trust\_index->score** (integer)  
The overall trust index score.

**latest\_scored\_event->trust\_index->model** (string)  
The versioned name of the Trust Index model used for scoring.

**latest\_scored\_event->trust\_index->subscores** (nullable, object)  
Contains sub-score metadata.

**latest\_scored\_event->trust\_index->subscores->device\_and\_connection** (nullable, object)  
Represents Trust Index Subscore.

**latest\_scored\_event->trust\_index->subscores->device\_and\_connection->score** (integer)  
The subscore score.

**latest\_scored\_event->trust\_index->subscores->bank\_account\_insights** (nullable, object)  
Represents Trust Index Subscore.

**latest\_scored\_event->trust\_index->subscores->bank\_account\_insights->score** (integer)  
The subscore score.

**latest\_scored\_event->fraud\_attributes** (nullable, object)  
Event fraud attributes as an arbitrary set of key-value pairs.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "user_id": "plaid-user-6009db6e",
  "latest_scored_event": {
    "event_id": "protect-event-2be8498f",
    "timestamp": "2020-07-24T03:26:02Z",
    "trust_index": {
      "score": 86,
      "model": "ti-pro-1.0",
      "subscores": {
        "device_and_connection": {
          "score": 87
        },
        "bank_account_insights": {
          "score": 85
        }
      }
    },
    "fraud_attributes": {
      "num_distinct_names_on_accounts": 3,
      "identity_match_idv_bank_account": true,
      "idv_id_doc_passed": true
    }
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

### Webhooks 

\=\*=\*=\*=

#### PROTECT\_USER\_EVENT 

Fired when there has been a new user event. The webhook payload contains limited information about the event. For full event details, call [/protect/event/get](https://plaid.com/docs/api/products/protect/index.html.md#protecteventget) .

#### Properties 

**webhook\_type** (string)  
"PROTECT"

**webhook\_code** (string)  
PROTECT\_USER\_EVENT

**event\_id** (string)  
The event ID of the user event that occurred.

**event\_type** (string)  
The type of user event that occurred.

**timestamp** (string)  
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**user\_id** (string)  
The Plaid User ID.

```json
{
  "webhook_type": "PROTECT",
  "webhook_code": "PROTECT_USER_EVENT",
  "user_id": "plaid-user-6009db6e",
  "event_id": "protect-event-2be8498f",
  "timestamp": "2020-07-24T03:26:02Z",
  "event_type": "LINK_COMPLETE"
}
```

---


# API - Signal | Plaid Docs

Signal endpoints 
=================

#### API Reference guide for the Signal product 

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

| Endpoints |  |
| --- | --- |
| [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) | Retrieve Signal scores |
| [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) | Report whether you initiated an ACH transaction |
| [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) | Report a return for an ACH transaction |
| [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) | Add Signal to an existing Item |

| See also |  |
| --- | --- |
| [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | Create a token for using Signal with a processing partner |
| [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) | Retrieve Signal scores as a processor partner |
| [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) | Report whether you initiated an ACH transaction as a processor partner |
| [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) | Report a return for an ACH transaction as a processor partner |
| [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) | Prepare a processor token for Signal |

\=\*=\*=\*=

#### /signal/evaluate 

#### Evaluate a planned ACH transaction 

Use [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) to evaluate a planned ACH transaction to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.  
In order to obtain a valid score for an ACH transaction, Plaid must have an access token for the account, and the Item must be healthy (receiving product updates) or have recently been in a healthy state. If the transaction does not meet eligibility requirements, an error will be returned corresponding to the underlying cause. If [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is called on the same transaction multiple times within a 24-hour period, cached results may be returned. For more information please refer to the error documentation on [Item errors](https://plaid.com/docs/errors/item/index.html.md) and [Link in Update Mode](https://plaid.com/docs/link/update-mode/index.html.md) .  
Note: This request may take some time to complete if Signal is being added to an existing Item. This is because Plaid must communicate directly with the institution when retrieving the data for the first time.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**account\_id** (required, string)  
The Plaid account\_id of the account that is the funding source for the proposed transaction. The account\_id is returned in the /accounts/get endpoint as well as the onSuccess callback metadata. This will return an INVALID\_ACCOUNT\_ID error if the account has been removed at the bank or if the account\_id is no longer valid.

**client\_transaction\_id** (required, string)  
The unique ID that you would like to use to refer to this evaluation attempt - for example, a payment attempt ID. You will use this later to debug this evaluation, and/or report an ACH return, etc. The max length for this field is 36 characters. Min length: 1 Max length: 36

**amount** (required, number)  
The transaction amount, in USD (e.g. 102.05) Format: double

**user\_present** (boolean)  
true if the end user is present while initiating the ACH transfer and the endpoint is being called; false otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing).

**client\_user\_id** (string)  
A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the client\_user\_id.

**is\_recurring** (boolean)  
Use true if the ACH transaction is a part of recurring schedule (for example, a monthly repayment); false otherwise

**default\_payment\_method** (string)  
The default ACH payment method to complete the transaction. SAME\_DAY\_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day STANDARD\_ACH: standard ACH by NACHA MULTIPLE\_PAYMENT\_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME\_DAY\_ACH, STANDARD\_ACH, MULTIPLE\_PAYMENT\_METHODS

**user** (object)  
Details about the end user initiating the transaction (i.e., the account holder). When calling /signal/evaluate or /signal/processor/evaluate, this field is optional, but strongly recommended to increase the accuracy of Signal results.

**user->name** (object)  
The user's legal name

**user->name->prefix** (string)  
The user's name prefix (e.g. "Mr.")

**user->name->given\_name** (string)  
The user's given name. If the user has a one-word name, it should be provided in this field.

**user->name->middle\_name** (string)  
The user's middle name

**user->name->family\_name** (string)  
The user's family name / surname

**user->name->suffix** (string)  
The user's name suffix (e.g. "II")

**user->phone\_number** (string)  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567"

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
Data about the components comprising an address.

**user->address->city** (string)  
The full city name

**user->address->region** (string)  
The region or state Example: "NC"

**user->address->street** (string)  
The full street address Example: "564 Main Street, APT 15"

**user->address->postal\_code** (string)  
The postal code

**user->address->country** (string)  
The ISO 3166-1 alpha-2 country code

**device** (object)  
Details about the end user's device. When calling /signal/evaluate or /signal/processor/evaluate, this field is optional, but strongly recommended to increase the accuracy of Signal results.

**device->ip\_address** (string)  
The IP address of the device that initiated the transaction

**device->user\_agent** (string)  
The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0")

**ruleset\_key** (string)  
The key of the ruleset to use for evaluating this transaction. You can configure a ruleset using the Signal dashboard located within the Plaid Dashboard. If not provided, no ruleset will be used.

```javascript
const eval_request = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  client_transaction_id: 'txn12345',
  amount: 123.45,
  client_user_id: 'user1234',
  user: {
    name: {
      prefix: 'Ms.',
      given_name: 'Jane',
      middle_name: 'Leah',
      family_name: 'Doe',
      suffix: 'Jr.',
    },
    phone_number: '+14152223333',
    email_address: 'jane.doe@example.com',
    address: {
      street: '2493 Leisure Lane',
      city: 'San Matias',
      region: 'CA',
      postal_code: '93405-2255',
      country: 'US',
    },
  },
  device: {
    ip_address: '198.30.2.2',
    user_agent:
      'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1',
  },
  user_present: true,
};


try {
  const eval_response = await plaidClient.signalEvaluate(eval_request);
  const core_attributes = eval_response.data.core_attributes;
  const scores = eval_response.data.scores;
} catch (error) {
  // handle error
}
```

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

**scores** (nullable, object)  
Risk scoring details broken down by risk category.

**scores->customer\_initiated\_return\_risk** (object)  
The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.

**scores->customer\_initiated\_return\_risk->score** (integer)  
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: 1 Maximum: 99

**scores->bank\_initiated\_return\_risk** (object)  
The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.

**scores->bank\_initiated\_return\_risk->score** (integer)  
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: 1 Maximum: 99

**core\_attributes** (object)  
The core attributes object contains additional data that can be used to assess the ACH return risk. Examples of data include: days\_since\_first\_plaid\_connection: The number of days since the first time the Item was connected to an application via Plaid plaid\_connections\_count\_7d: The number of times the Item has been connected to applications via Plaid over the past 7 days plaid\_connections\_count\_30d: The number of times the Item has been connected to applications via Plaid over the past 30 days total\_plaid\_connections\_count: The number of times the Item has been connected to applications via Plaid is\_savings\_or\_money\_market\_account: Indicates whether the ACH transaction funding account is a savings/money market account For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager

**ruleset** (nullable, object)  
Details about the transaction result after evaluated by the requested Ruleset. If a ruleset\_key is not provided, this field will be omitted. This feature is currently in closed beta; to request access, contact your account manager.

**ruleset->ruleset\_key** (string)  
The key of the Ruleset used for this transaction.

**ruleset->result** (string)  
The result of the rule that was triggered for this transaction. ACCEPT: Accept the transaction for processing. REROUTE: Reroute the transaction to a different payment method, as this transaction is too risky. REVIEW: Review the transaction before proceeding. Possible values: ACCEPT, REROUTE, REVIEW

**ruleset->triggered\_rule\_details** (nullable, object)  
Rules are run in numerical order. The first rule with a logic match is triggered. These are the details of that rule.

**ruleset->triggered\_rule\_details->internal\_note** (string)  
An optional message attached to the triggered rule, defined within the Dashboard, for your internal use. Useful for debugging, such as “Account appears to be closed.”

**ruleset->triggered\_rule\_details->custom\_action\_key** (string)  
A string key, defined within the Dashboard, used to trigger programmatic behavior for a certain result. For instance, you could optionally choose to define a "3-day-hold" custom\_action\_key for an ACCEPT result.

**ruleset->outcome** (deprecated, string)  
The evaluated outcome for this transaction. This field is deprecated, use result or triggered\_rule\_details.custom\_action\_key instead.

**warnings** (\[object\])  
If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.

**warnings->warning\_type** (string)  
A broad categorization of the warning. Safe for programmatic use.

**warnings->warning\_code** (string)  
The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. If you receive the ITEM\_LOGIN\_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.

**warnings->warning\_message** (string)  
A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.

```json
{
  "scores": {
    "customer_initiated_return_risk": {
      "score": 9
    },
    "bank_initiated_return_risk": {
      "score": 82
    }
  },
  "core_attributes": {
    "days_since_first_plaid_connection": 510,
    "plaid_connections_count_7d": 6,
    "plaid_connections_count_30d": 7,
    "total_plaid_connections_count": 15,
    "is_savings_or_money_market_account": false
  },
  "ruleset": {
    "ruleset_key": "onboarding_flow",
    "result": "REROUTE",
    "triggered_rule_details": {
      "internal_note": "Rerouting customer to different payment method, since bank risk score is too high"
    }
  },
  "warnings": [],
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /signal/decision/report 

#### Report whether you initiated an ACH transaction 

After calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , call [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) to report whether the transaction was initiated.

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

**client\_transaction\_id** (required, string)  
Must be the same as the client\_transaction\_id supplied when calling /signal/evaluate Min length: 1 Max length: 36

**initiated** (required, boolean)  
true if the ACH transaction was initiated, false otherwise. This field must be returned as a boolean. If formatted incorrectly, this will result in an INVALID\_FIELD error.

**days\_funds\_on\_hold** (integer)  
The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate. For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization. Minimum: 0

**decision\_outcome** (string)  
The payment decision from the risk assessment. APPROVE: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers. REVIEW: the transaction requires manual review REJECT: reject the transaction TAKE\_OTHER\_RISK\_MEASURES: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication NOT\_EVALUATED: if only logging the Signal results without using them Possible values: APPROVE, REVIEW, REJECT, TAKE\_OTHER\_RISK\_MEASURES, NOT\_EVALUATED

**payment\_method** (string)  
The payment method to complete the transaction after the risk assessment. It may be different from the default payment method. SAME\_DAY\_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day STANDARD\_ACH: Standard ACH by NACHA MULTIPLE\_PAYMENT\_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME\_DAY\_ACH, STANDARD\_ACH, MULTIPLE\_PAYMENT\_METHODS

**amount\_instantly\_available** (number)  
The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05). Format: double

```javascript
const decision_report_request = {
  client_transaction_id: 'txn12345',
  initiated: true,
  days_funds_on_hold: 3,
};


try {
  const decision_report_response = await plaidClient.signalDecisionReport(
    decision_report_request,
  );
  const decision_request_id = decision_report_response.data.request_id;
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /signal/return/report 

#### Report a return for an ACH transaction 

Call the [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) endpoint to report a returned transaction that was previously sent to the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio.

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

**client\_transaction\_id** (required, string)  
Must be the same as the client\_transaction\_id supplied when calling /signal/evaluate or /accounts/balance/get. Min length: 1 Max length: 36

**return\_code** (required, string)  
Must be a valid ACH return code (e.g. "R01") If formatted incorrectly, this will result in an INVALID\_FIELD error.

**returned\_at** (string)  
Date and time when you receive the returns from your payment processors, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Format: date-time

```javascript
const return_report_request = {
  client_transaction_id: 'txn12345',
  return_code: 'R01',
};


try {
  const return_report_response = await plaidClient.signalReturnReport(
    return_report_request,
  );
  const request_id = return_report_response.data.request_id;
  console.log(request_id);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /signal/prepare 

#### Opt-in an Item to Signal 

When an Item is not initialized with Signal, call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) to opt-in that Item to the Signal data collection process, developing a Signal score. This should be done on Items where Signal was added in the `additional_consented_products` array but not in the `products`, `optional_products`, or `required_if_supported_products` array. If [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) is skipped on an Item that is not initialized with Signal, the initial call to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) on that Item will be less accurate, because Signal will have access to less data for computing the Signal score.  
If run on an Item that is already initialized with Signal, this endpoint will return a 200 response and will not modify the Item.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

```javascript
const prepare_request = {
  client_id: '7f57eb3d2a9j6480121fx361',
  secret: '79g03eoofwl8240v776r2h667442119',
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
};


try {
  const prepare_response = await plaidClient.signalPrepare(prepare_request);
  const request_id = prepare_response.data.request_id;
  console.log(request_id);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

---


# API - Statements | Plaid Docs

Statements 
===========

#### API reference for Statements endpoints and webhooks 

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

| Endpoint | Description |
| --- | --- |
| [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) | Get a list of statements available to download |
| [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) | Download a single bank statement |
| [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) | Trigger on-demand statement extractions |

| Webhook Name | Description |
| --- | --- |
| [STATEMENTS\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/statements/index.html.md#statements_refresh_complete) | Statements refresh completed |

### Endpoints 

\=\*=\*=\*=

#### /statements/list 

#### Retrieve a list of all statements associated with an item. 

The [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) endpoint retrieves a list of all statements associated with an item.

#### Request fields 

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

```javascript
const listRequest: StatementsListRequest = {
  access_token: access_token,
};
const listResponse = await plaidClient.statementsList(listRequest);
accounts = listResponse.accounts;
statements = listResponse.accounts[0].statements;
```

#### Response fields and example 

string

**accounts** (\[object\])  
Plaid's unique identifier for the account.

**accounts->account\_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, and it may also not match the mask that the bank displays to the user.

**accounts->account\_name** (string)  
The name of the account, either assigned by the user or by the financial institution itself.

**accounts->account\_official\_name** (string)  
The official name of the account as given by the financial institution.

**accounts->account\_subtype** (string)  
The subtype of the account. For a full list of valid types and subtypes, see the Account schema.

**accounts->account\_type** (string)  
The type of account. For a full list of valid types and subtypes, see the Account schema.

**accounts->statements** (\[object\])  
The list of statements' metadata associated with this account.

**accounts->statements->statement\_id** (string)  
Plaid's unique identifier for the statement.

**accounts->statements->date\_posted** (nullable, string)  
Date when the statement was posted by the FI, if known Format: date

**accounts->statements->month** (integer)  
Month of the year. Possible values: 1 through 12 (January through December).

**accounts->statements->year** (integer)  
The year of statement. Minimum: 2010

**institution\_id** (string)  
The Plaid Institution ID associated with the Item.

**institution\_name** (string)  
The name of the institution associated with the Item.

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

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "institution_id": "ins_3",
  "institution_name": "Chase",
  "accounts": [
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "account_mask": "0000",
      "account_name": "Plaid Saving",
      "account_official_name": "Plaid Silver Standard 0.1% Interest Saving",
      "account_subtype": "savings",
      "account_type": "depository",
      "statements": [
        {
          "statement_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
          "month": 5,
          "year": 2023,
          "date_posted": "2023-05-01"
        }
      ]
    }
  ],
  "request_id": "eYupqX1mZkEuQRx"
}
```

\=\*=\*=\*=

#### /statements/download 

#### Retrieve a single statement. 

The [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) endpoint retrieves a single statement PDF in binary format. The response will contain a `Plaid-Content-Hash` header containing a SHA 256 checksum of the statement. This can be used to verify that the file being sent by Plaid is the same file that was downloaded to your system.

#### Request fields 

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

**statement\_id** (required, string)  
Plaid's unique identifier for the statements.

```javascript
let downloadRequest: StatementsDownloadRequest = {
  access_token: accessToken,
  statement_id: statement.statement_id,
};
let downloadResponse = await plaidClient.statementsDownload(
  downloadRequest,
  {responseType: 'arraybuffer'},
);
let pdf = downloadResponse.data.toString('base64');
```

##### Response 

This endpoint returns a single statement, exactly as provided by the financial institution, in the form of binary PDF data.

\=\*=\*=\*=

#### /statements/refresh 

#### Refresh statements data. 

[/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) initiates an on-demand extraction to fetch the statements for the provided dates.

#### Request fields 

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

**start\_date** (required, string)  
The start date for statements, in "YYYY-MM-DD" format, e.g. "2023-08-30". To determine whether a statement falls within the specified date range, Plaid will use the statement posted date. The statement posted date is typically either the last day of the statement period, or the following day. Format: date

**end\_date** (required, string)  
The end date for statements, in "YYYY-MM-DD" format, e.g. "2023-10-30". You can request up to two years of data. To determine whether a statement falls within the specified date range, Plaid will use the statement posted date. The statement posted date is typically either the last day of the statement period, or the following day. Format: date

```javascript
const refreshRequest: StatementsRefreshRequest = {
  access_token: accessToken,
  start_date: '2023-11-01',
  end_date: '2024-02-01',
};
const refreshResponse = await plaidClient.statementsRefresh(refreshRequest);
```

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

```json
{
  "request_id": "eYupqX1mZkEuQRx"
}
```

### Webhooks 

Statement webhooks are sent to indicate that statements refresh has finished processing. All webhooks related to statements have a `webhook_type` of `STATEMENTS`.

\=\*=\*=\*=

#### STATEMENTS\_REFRESH\_COMPLETE 

Fired when refreshed statements extraction is completed or failed to be completed. Triggered by calling [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) .

#### Properties 

**webhook\_type** (string)  
STATEMENTS

**webhook\_code** (string)  
STATEMENTS\_REFRESH\_COMPLETE

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

**result** (string)  
The result of the statement refresh extraction SUCCESS: The statements were successfully extracted and can be listed via /statements/list/ and downloaded via /statements/download/. FAILURE: The statements failed to be extracted. Possible values: SUCCESS, FAILURE

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "STATEMENTS",
  "webhook_code": "STATEMENTS_REFRESH_COMPLETE",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "result": "SUCCESS",
  "environment": "production"
}
```

---


# API - Transactions | Plaid Docs

Transactions 
=============

#### API reference for Transactions endpoints and webhooks 

Retrieve and refresh up to 24 months of historical transaction data, including geolocation, merchant, and category information. For how-to guidance, see the [Transactions documentation](https://plaid.com/docs/transactions/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | Get transaction data or incremental transaction updates |
| [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | Fetch transaction data |
| [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) | Fetch recurring transaction data |
| [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) | Refresh transaction data |
| [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) | Fetch all transaction categories |

| See also |  |
| --- | --- |
| [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) | Get transaction data or incremental transaction updates |
| [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) | Fetch transaction data |
| [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) | Fetch recurring transaction data |
| [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) | Refresh transaction data |
| [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) | Create custom transactions for testing |

| Webhooks |  |
| --- | --- |
| [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) | New updates available |
| [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) | New recurring updates available |
| [INITIAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#initial_update) | Initial transactions ready |
| [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) | Historical transactions ready |
| [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) | New transactions available |
| [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) | Deleted transactions detected |

### Endpoints 

\=\*=\*=\*=

#### /transactions/sync 

If you are migrating to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) from an existing [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) integration, also refer to the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) .

#### Get incremental transaction updates on an Item 

The [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint retrieves transactions associated with an Item and can fetch updates using a cursor to track which updates have already been seen.  
For important instructions on integrating with [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , see the [Transactions integration overview](https://plaid.com/docs/transactions/index.html.md#integration-overview) . If you are migrating from an existing integration using [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , see the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) .  
This endpoint supports `credit`, `depository`, and some `loan`\-type accounts (only those with account subtype `student`). For `investments` accounts, use [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) instead.  
When retrieving paginated updates, track both the `next_cursor` from the latest response and the original cursor from the first call in which `has_more` was `true`; if a call to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) fails when retrieving a paginated update (e.g due to the [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) error), the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.  
If transactions data is not yet available for the Item, which can happen if the Item was not initialized with transactions during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call or if [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) was called within a few seconds of Item creation, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) will return empty transactions arrays.  
Plaid typically checks for new transactions data between one and four times per day, depending on the institution. To find out when transactions were last updated for an Item, use the [Item Debugger](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-with-item-debugger) or call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) ; the `item.status.transactions.last_successful_update` field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint.  
To be alerted when new transactions are available, listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

**cursor** (string)  
The cursor value represents the last update requested. Providing it will cause the response to only return changes after this update. If omitted, the entire history of updates will be returned, starting with the first-added transactions on the Item. The cursor also accepts the special value of "now", which can be used to fast-forward the cursor as part of migrating an existing Item from /transactions/get to /transactions/sync. For more information, see the Transactions sync migration guide. Note that using the "now" value is not supported for any use case other than migrating existing Items from /transactions/get. The upper-bound length of this cursor is 256 characters of base64.

**count** (integer)  
The number of transaction updates to fetch. Default: 100 Minimum: 1 Maximum: 500 Exclusive min: false

**options** (object)  
An optional object to be used with the request. If specified, options must not be null.

**options->include\_original\_description** (boolean)  
Include the raw unparsed transaction description from the financial institution. Default: false

**options->days\_requested** (integer)  
This field only applies to calls for Items where the Transactions product has not already been initialized (i.e., by specifying transactions in the products, required\_if\_supported\_products, or optional\_products array when calling /link/token/create or by making a previous call to /transactions/sync or /transactions/get). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. If you are initializing your Items with transactions during the /link/token/create call (e.g. by including transactions in the /link/token/create products array), you must use the transactions.days\_requested field in the /link/token/create request instead of in the /transactions/sync request. If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via /item/remove and send the user through Link to create a new Item. Customers using Recurring Transactions should request at least 180 days of history for optimal results. Minimum: 1 Maximum: 730 Default: 90

**options->account\_id** (string)  
If provided, the returned updates and cursor will only reflect the specified account's transactions. Omitting account\_id returns updates for all accounts under the Item. Note that specifying an account\_id effectively creates a separate incremental update stream—and therefore a separate cursor—for that account. If multiple accounts are queried this way, you will maintain multiple cursors, one per account\_id. If you decide to begin filtering by account\_id after using no account\_id, start fresh with a null cursor and maintain separate (account\_id, cursor) pairs going forward. Do not reuse any previously saved cursors, as this can cause pagination errors or incomplete data. Note: An error will be returned if a provided account\_id is not associated with the Item.

```javascript
// Provide a cursor from your database if you've previously
// received one for the Item. Leave null if this is your
// first sync call for this Item. The first request will
// return a cursor.
let cursor = database.getLatestCursorOrNull(itemId);


// New transaction updates since "cursor"
let added: Array = [];
let modified: Array = [];
// Removed transaction ids
let removed: Array = [];
let hasMore = true;


// Iterate through each page of new transaction updates for item
while (hasMore) {
  const request: TransactionsSyncRequest = {
    access_token: accessToken,
    cursor: cursor,
  };
  const response = await client.transactionsSync(request);
  const data = response.data;


  // Add this page of results
  added = added.concat(data.added);
  modified = modified.concat(data.modified);
  removed = removed.concat(data.removed);


  hasMore = data.has_more;


  // Update cursor to the next cursor
  cursor = data.next_cursor;
}


// Persist cursor and updated data
database.applyUpdates(itemId, added, modified, removed, cursor);
```

#### Response fields and example 

**transactions\_update\_status** (string)  
A description of the update status for transaction pulls of an Item. This field contains the same information provided by transactions webhooks, and may be helpful for webhook troubleshooting or when recovering from missed webhooks. TRANSACTIONS\_UPDATE\_STATUS\_UNKNOWN: Unable to fetch transactions update status for Item. NOT\_READY: The Item is pending transaction pull. INITIAL\_UPDATE\_COMPLETE: Initial pull for the Item is complete, historical pull is pending. HISTORICAL\_UPDATE\_COMPLETE: Both initial and historical pull for Item are complete. Possible values: TRANSACTIONS\_UPDATE\_STATUS\_UNKNOWN, NOT\_READY, INITIAL\_UPDATE\_COMPLETE, HISTORICAL\_UPDATE\_COMPLETE

**accounts** (\[object\])  
An array of accounts at a financial institution associated with the transactions in this response. Only accounts that have associated transactions will be shown. For example, investment-type accounts will be omitted.

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**added** (\[object\])  
Transactions that have been added to the Item since cursor ordered by ascending last modified time.

**added->account\_id** (string)  
The ID of the account in which this transaction occurred.

**added->amount** (number)  
The settled value of the transaction, denominated in the transactions's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: double

**added->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**added->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**added->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**added->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized\_date field. Format: date

**added->location** (object)  
A representation of where a transaction took place

**added->location->address** (nullable, string)  
The street address where the transaction occurred.

**added->location->city** (nullable, string)  
The city where the transaction occurred.

**added->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**added->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**added->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**added->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**added->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**added->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**added->name** (deprecated, string)  
The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use merchant\_name instead for the merchant name. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**added->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**added->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field will only be included if the client has set options.include\_original\_description to true.

**added->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**added->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**added->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**added->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**added->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**added->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**added->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**added->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**added->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**added->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.

**added->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions.

**added->account\_owner** (nullable, string)  
This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution.

**added->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**added->transaction\_type** (deprecated, string)  
Please use the payment\_channel field, transaction\_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**added->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**added->website** (nullable, string)  
The website associated with this transaction, if available.

**added->authorized\_date** (nullable, string)  
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized\_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**added->authorized\_datetime** (nullable, string)  
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized\_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**added->datetime** (nullable, string)  
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized\_datetime field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**added->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. This field replaces the transaction\_type field. Possible values: online, in store, other

**added->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**added->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**added->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**added->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**added->transaction\_code** (nullable, string)  
An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. adjustment: Bank adjustment atm: Cash deposit or withdrawal via an automated teller machine bank charge: Charge or fee levied by the institution bill payment: Payment of a bill cash: Cash deposit or withdrawal cashback: Cash withdrawal while making a debit card purchase cheque: Document ordering the payment of money to another person or organization direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval interest: Interest earned or incurred purchase: Purchase made with a debit or credit card standing order: Payment instructed by the account holder to a third party at a regular interval transfer: Transfer of money between accounts Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null

**added->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**added->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**added->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**added->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**added->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**added->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**added->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**added->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**added->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**added->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**added->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**added->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**added->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**added->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**added->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**added->merchant\_entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store.

**modified** (\[object\])  
Transactions that have been modified on the Item since cursor ordered by ascending last modified time.

**modified->account\_id** (string)  
The ID of the account in which this transaction occurred.

**modified->amount** (number)  
The settled value of the transaction, denominated in the transactions's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: double

**modified->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**modified->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**modified->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**modified->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized\_date field. Format: date

**modified->location** (object)  
A representation of where a transaction took place

**modified->location->address** (nullable, string)  
The street address where the transaction occurred.

**modified->location->city** (nullable, string)  
The city where the transaction occurred.

**modified->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**modified->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**modified->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**modified->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**modified->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**modified->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**modified->name** (deprecated, string)  
The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use merchant\_name instead for the merchant name. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**modified->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**modified->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field will only be included if the client has set options.include\_original\_description to true.

**modified->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**modified->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**modified->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**modified->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**modified->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**modified->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**modified->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**modified->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**modified->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**modified->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.

**modified->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions.

**modified->account\_owner** (nullable, string)  
This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution.

**modified->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**modified->transaction\_type** (deprecated, string)  
Please use the payment\_channel field, transaction\_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**modified->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**modified->website** (nullable, string)  
The website associated with this transaction, if available.

**modified->authorized\_date** (nullable, string)  
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized\_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**modified->authorized\_datetime** (nullable, string)  
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized\_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**modified->datetime** (nullable, string)  
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized\_datetime field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**modified->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. This field replaces the transaction\_type field. Possible values: online, in store, other

**modified->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**modified->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**modified->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**modified->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**modified->transaction\_code** (nullable, string)  
An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. adjustment: Bank adjustment atm: Cash deposit or withdrawal via an automated teller machine bank charge: Charge or fee levied by the institution bill payment: Payment of a bill cash: Cash deposit or withdrawal cashback: Cash withdrawal while making a debit card purchase cheque: Document ordering the payment of money to another person or organization direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval interest: Interest earned or incurred purchase: Purchase made with a debit or credit card standing order: Payment instructed by the account holder to a third party at a regular interval transfer: Transfer of money between accounts Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null

**modified->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**modified->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**modified->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**modified->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**modified->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**modified->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**modified->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**modified->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**modified->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**modified->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**modified->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**modified->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**modified->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**modified->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**modified->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**modified->merchant\_entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store.

**removed** (\[object\])  
Transactions that have been removed from the Item since cursor ordered by ascending last modified time.

**removed->transaction\_id** (string)  
The ID of the removed transaction.

**removed->account\_id** (string)  
The ID of the account of the removed transaction.

**next\_cursor** (string)  
Cursor used for fetching any future updates after the latest update provided in this response. The cursor obtained after all pages have been pulled (indicated by has\_more being false) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string. If account\_id is included in the request, the returned cursor will reflect updates for that specific account.

**has\_more** (boolean)  
Represents if more than requested count of transaction updates exist. If true, the additional updates can be fetched by making an additional request with cursor set to next\_cursor. If has\_more is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 110.94,
        "current": 110.94,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "added": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 72.1,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "Walmart",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
          "website": "walmart.com",
          "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-24",
      "datetime": "2023-09-24T11:01:01Z",
      "authorized_date": "2023-09-22",
      "authorized_datetime": "2023-09-22T10:34:50Z",
      "location": {
        "address": "13425 Community Rd",
        "city": "Poway",
        "region": "CA",
        "postal_code": "92064",
        "country": "US",
        "lat": 32.959068,
        "lon": -117.037666,
        "store_number": "1700"
      },
      "name": "PURCHASE WM SUPERCENTER #1700",
      "merchant_name": "Walmart",
      "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
      "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
      "website": "walmart.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "in store",
      "pending": false,
      "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "personal_finance_category": {
        "primary": "GENERAL_MERCHANDISE",
        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "transaction_code": null,
      "transaction_type": "place"
    }
  ],
  "modified": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 28.34,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "DoorDash",
          "type": "marketplace",
          "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",
          "website": "doordash.com",
          "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",
          "confidence_level": "HIGH"
        },
        {
          "name": "Burger King",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
          "website": "burgerking.com",
          "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-28",
      "datetime": "2023-09-28T15:10:09Z",
      "authorized_date": "2023-09-27",
      "authorized_datetime": "2023-09-27T08:01:58Z",
      "location": {
        "address": null,
        "city": null,
        "region": null,
        "postal_code": null,
        "country": null,
        "lat": null,
        "lon": null,
        "store_number": null
      },
      "name": "Dd Doordash Burgerkin",
      "merchant_name": "Burger King",
      "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
      "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
      "website": "burgerking.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "online",
      "pending": true,
      "pending_transaction_id": null,
      "personal_finance_category": {
        "primary": "FOOD_AND_DRINK",
        "detailed": "FOOD_AND_DRINK_FAST_FOOD",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",
      "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
      "transaction_code": null,
      "transaction_type": "digital"
    }
  ],
  "removed": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
    }
  ],
  "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV",
  "has_more": false,
  "request_id": "Wvhy9PZHQLV8njG",
  "transactions_update_status": "HISTORICAL_UPDATE_COMPLETE"
}
```

\=\*=\*=\*=

#### /transactions/get 

#### Get transaction data 

Note: All new implementations are encouraged to use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) rather than [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) provides the same functionality as [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) and improves developer ease-of-use for handling transactions updates.  
The [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype `student`; coverage may be limited). For transaction history from investments accounts, use the [Investments endpoint](https://plaid.com/docs/api/products/investments/index.html.md) instead. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.  
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . For more details, see [Pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#pending-and-posted-transactions) .  
Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the `count` and `offset` parameters in conjunction with the `total_transactions` response body field to fetch all available transactions.  
Data returned by [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) will be the data available for the Item as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To find out when the Item was last updated, use the [Item Debugger](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-with-item-debugger) or call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) ; the `item.status.transactions.last_successful_update` field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, you can use the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint.  
Note that data may not be immediately available to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . Plaid will begin to prepare transactions data upon Item link, if Link was initialized with `transactions`, or upon the first call to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , if it wasn't. To be alerted when transaction data is ready to be fetched, listen for the [INITIAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#initial_update) and [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) webhooks. If no transaction history is ready when [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) is called, it will return a `PRODUCT_NOT_READY` error.

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

**options** (object)  
An optional object to be used with the request. If specified, options must not be null.

**options->account\_ids** (\[string\])  
A list of account\_ids to retrieve for the Item Note: An error will be returned if a provided account\_id is not associated with the Item.

**options->count** (integer)  
The number of transactions to fetch. Default: 100 Minimum: 1 Maximum: 500 Exclusive min: false

**options->offset** (integer)  
The number of transactions to skip. The default value is 0. Default: 0 Minimum: 0

**options->include\_original\_description** (boolean)  
Include the raw unparsed transaction description from the financial institution. Default: false

**options->days\_requested** (integer)  
This field only applies to calls for Items where the Transactions product has not already been initialized (i.e. by specifying transactions in the products, optional\_products, or required\_if\_consented\_products array when calling /link/token/create or by making a previous call to /transactions/sync or /transactions/get). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. If a value under 30 is provided, a minimum of 30 days of history will be requested. If you are initializing your Items with transactions during the /link/token/create call (e.g. by including transactions in the /link/token/create products array), you must use the transactions.days\_requested field in the /link/token/create request instead of in the /transactions/get request. If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via /item/remove and send the user through Link to create a new Item. Customers using Recurring Transactions should request at least 180 days of history for optimal results. Minimum: 1 Maximum: 730 Default: 90

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

**start\_date** (required, string)  
The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date

**end\_date** (required, string)  
The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date

```javascript
const request: TransactionsGetRequest = {
  access_token: accessToken,
  start_date: '2018-01-01',
  end_date: '2020-02-01'
};
try {
  const response = await client.transactionsGet(request);
  let transactions = response.data.transactions;
  const total_transactions = response.data.total_transactions;
  // Manipulate the offset parameter to paginate
  // transactions and retrieve all available data
  while (transactions.length < total_transactions) {
    const paginatedRequest: TransactionsGetRequest = {
      access_token: accessToken,
      start_date: '2018-01-01',
      end_date: '2020-02-01',
      options: {
        offset: transactions.length
      },
    };
    const paginatedResponse = await client.transactionsGet(paginatedRequest);
    transactions = transactions.concat(
      paginatedResponse.data.transactions,
    );
  }
} catch((err) => {
  // handle error
}
```

#### Response fields and example 

**accounts** (\[object\])  
An array containing the accounts associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the account\_id field.

**accounts->account\_id** (string)  
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account\_id will be assigned to the account. The account\_id can also change if the access\_token is deleted and the same credentials that were used to generate that access\_token are used to generate a new access\_token on a later date. In that case, the new account\_id will be different from the old account\_id. If an account with a specific account\_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with /cra/), the account\_id returned will not match the account\_id returned by a non-CRA endpoint. Like all Plaid identifiers, the account\_id is case sensitive.

**accounts->balances** (object)  
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.

**accounts->balances->available** (nullable, number)  
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null. Format: double

**accounts->balances->current** (nullable, number)  
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins\_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to credit-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. Format: double

**accounts->balances->limit** (nullable, number)  
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts. Format: double

**accounts->balances->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the balance. Always null if unofficial\_currency\_code is non-null.

**accounts->balances->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the balance. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported unofficial\_currency\_codes.

**accounts->balances->last\_updated\_datetime** (nullable, string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the balance was updated. This field is returned only when the institution is ins\_128026 (Capital One). Format: date-time

**accounts->mask** (nullable, string)  
The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts.

**accounts->name** (string)  
The name of the account, either assigned by the user or by the financial institution itself

**accounts->official\_name** (nullable, string)  
The official name of the account as given by the financial institution

**accounts->type** (string)  
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead. credit: Credit card depository: Depository account loan: Loan account other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other

**accounts->subtype** (nullable, string)  
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity

**accounts->verification\_status** (string)  
The current verification status of an Auth Item initiated through micro-deposits or database verification. Returned for Auth Items only. 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 micro-deposit. 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\_matched: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. 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\_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. Possible values: automatically\_verified, pending\_automatic\_verification, pending\_manual\_verification, unsent, manually\_verified, verification\_expired, verification\_failed, database\_matched, database\_insights\_pass, database\_insights\_pass\_with\_caution, database\_insights\_fail

**accounts->verification\_name** (string)  
The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the user.legal\_name request field in /link/token/create for the Link session that created the Item.

**accounts->verification\_insights** (object)  
Insights from performing database verification for the account. Only returned for Auth Items using Database Auth.

**accounts->verification\_insights->name\_match\_score** (nullable, integer)  
Indicates the score of the name match between the given name provided during database verification (available in the verification\_name field) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with.

**accounts->verification\_insights->network\_status** (object)  
Status information about the account and routing number in the Plaid network.

**accounts->verification\_insights->network\_status->has\_numbers\_match** (boolean)  
Indicates whether we found at least one matching account for the ACH account and routing number.

**accounts->verification\_insights->network\_status->is\_numbers\_match\_verified** (boolean)  
Indicates if at least one matching account for the ACH account and routing number is already verified.

**accounts->verification\_insights->previous\_returns** (object)  
Information about known ACH returns for the account and routing number.

**accounts->verification\_insights->previous\_returns->has\_previous\_administrative\_return** (boolean)  
Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.

**accounts->verification\_insights->account\_number\_format** (string)  
Indicator of account number format validity for institution. valid: indicates that the account number has a correct format for the institution. invalid: indicates that the account number has an incorrect format for the institution. unknown: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: valid, invalid, unknown

**accounts->persistent\_account\_id** (string)  
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (ins\_56, ins\_13) as well as the OAuth Sandbox institution (ins\_127287); in Production, it will only be populated for accounts at applicable institutions.

**accounts->holder\_category** (nullable, string)  
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: business, personal, unrecognized

**transactions** (\[object\])  
An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter.

**transactions->account\_id** (string)  
The ID of the account in which this transaction occurred.

**transactions->amount** (number)  
The settled value of the transaction, denominated in the transactions's currency, as stated in iso\_currency\_code or unofficial\_currency\_code. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: double

**transactions->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the transaction. Always null if unofficial\_currency\_code is non-null.

**transactions->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code associated with the transaction. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso\_currency\_codes.

**transactions->check\_number** (nullable, string)  
The check number of the transaction. This field is only populated for check transactions.

**transactions->date** (string)  
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized\_date field. Format: date

**transactions->location** (object)  
A representation of where a transaction took place

**transactions->location->address** (nullable, string)  
The street address where the transaction occurred.

**transactions->location->city** (nullable, string)  
The city where the transaction occurred.

**transactions->location->region** (nullable, string)  
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.

**transactions->location->postal\_code** (nullable, string)  
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.

**transactions->location->country** (nullable, string)  
The ISO 3166-1 alpha-2 country code where the transaction occurred.

**transactions->location->lat** (nullable, number)  
The latitude where the transaction occurred. Format: double

**transactions->location->lon** (nullable, number)  
The longitude where the transaction occurred. Format: double

**transactions->location->store\_number** (nullable, string)  
The merchant defined store number where the transaction occurred.

**transactions->name** (deprecated, string)  
The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use merchant\_name instead for the merchant name. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**transactions->merchant\_name** (nullable, string)  
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.

**transactions->original\_description** (nullable, string)  
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field will only be included if the client has set options.include\_original\_description to true.

**transactions->payment\_meta** (object)  
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment\_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset\_report/get/ or /asset\_report/pdf/get, this field will only appear in an Asset Report with Insights.

**transactions->payment\_meta->reference\_number** (nullable, string)  
The transaction reference number supplied by the financial institution.

**transactions->payment\_meta->ppd\_id** (nullable, string)  
The ACH PPD ID for the payer.

**transactions->payment\_meta->payee** (nullable, string)  
For transfers, the party that is receiving the transaction.

**transactions->payment\_meta->by\_order\_of** (nullable, string)  
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.

**transactions->payment\_meta->payer** (nullable, string)  
For transfers, the party that is paying the transaction.

**transactions->payment\_meta->payment\_method** (nullable, string)  
The type of transfer, e.g. 'ACH'

**transactions->payment\_meta->payment\_processor** (nullable, string)  
The name of the payment processor

**transactions->payment\_meta->reason** (nullable, string)  
The payer-supplied description of the transfer.

**transactions->pending** (boolean)  
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.

**transactions->pending\_transaction\_id** (nullable, string)  
The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions.

**transactions->account\_owner** (nullable, string)  
This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution.

**transactions->transaction\_id** (string)  
The unique ID of the transaction. Like all Plaid identifiers, the transaction\_id is case sensitive.

**transactions->transaction\_type** (deprecated, string)  
Please use the payment\_channel field, transaction\_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved

**transactions->logo\_url** (nullable, string)  
The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file.

**transactions->website** (nullable, string)  
The website associated with this transaction, if available.

**transactions->authorized\_date** (nullable, string)  
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized\_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date

**transactions->authorized\_datetime** (nullable, string)  
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized\_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized\_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**transactions->datetime** (nullable, string)  
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized\_datetime field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: date-time

**transactions->payment\_channel** (string)  
The channel used to make a payment. online: transactions that took place online. in store: transactions that were made at a physical location. other: transactions that relate to banks, e.g. fees or deposits. This field replaces the transaction\_type field. Possible values: online, in store, other

**transactions->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**transactions->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**transactions->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**transactions->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**transactions->transaction\_code** (nullable, string)  
An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. adjustment: Bank adjustment atm: Cash deposit or withdrawal via an automated teller machine bank charge: Charge or fee levied by the institution bill payment: Payment of a bill cash: Cash deposit or withdrawal cashback: Cash withdrawal while making a debit card purchase cheque: Document ordering the payment of money to another person or organization direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval interest: Interest earned or incurred purchase: Purchase made with a debit or credit card standing order: Payment instructed by the account holder to a third party at a regular interval transfer: Transfer of money between accounts Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null

**transactions->personal\_finance\_category\_icon\_url** (string)  
The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file.

**transactions->counterparties** (\[object\])  
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.

**transactions->counterparties->name** (string)  
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.

**transactions->counterparties->entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the counterparty.

**transactions->counterparties->type** (string)  
The counterparty type. merchant: a provider of goods or services for purchase financial\_institution: a financial entity (bank, credit union, BNPL, fintech) payment\_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment\_terminal: a point-of-sale payment terminal (e.g Square, Toast) income\_source: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: merchant, financial\_institution, payment\_app, marketplace, payment\_terminal, income\_source

**transactions->counterparties->website** (nullable, string)  
The website associated with the counterparty.

**transactions->counterparties->logo\_url** (nullable, string)  
The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file.

**transactions->counterparties->confidence\_level** (nullable, string)  
A description of how confident we are that the provided counterparty is involved in the transaction. VERY\_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: We don’t know the confidence level for this counterparty.

**transactions->counterparties->account\_numbers** (nullable, object)  
Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe.

**transactions->counterparties->account\_numbers->bacs** (nullable, object)  
Identifying information for a UK bank account via BACS.

**transactions->counterparties->account\_numbers->bacs->account** (nullable, string)  
The BACS account number for the account.

**transactions->counterparties->account\_numbers->bacs->sort\_code** (nullable, string)  
The BACS sort code for the account.

**transactions->counterparties->account\_numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**transactions->counterparties->account\_numbers->international->iban** (nullable, string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**transactions->counterparties->account\_numbers->international->bic** (nullable, string)  
Bank identifier code (BIC) for this counterparty. Min length: 8 Max length: 11

**transactions->merchant\_entity\_id** (nullable, string)  
A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store.

**total\_transactions** (integer)  
The total number of transactions available within the date range specified. If total\_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.

**item** (object)  
Metadata about the Item.

**item->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.

**item->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**item->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**item->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**item->error** (nullable, 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.

**item->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**item->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**item->error->error\_code\_reason** (nullable, 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.

**item->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**item->error->display\_message** (nullable, 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.

**item->error->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.

**item->error->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.

**item->error->status** (nullable, 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.

**item->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**item->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**item->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**item->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**item->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**item->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 110.94,
        "current": 110.94,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "transactions": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 28.34,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "DoorDash",
          "type": "marketplace",
          "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",
          "website": "doordash.com",
          "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",
          "confidence_level": "HIGH"
        },
        {
          "name": "Burger King",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
          "website": "burgerking.com",
          "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-28",
      "datetime": "2023-09-28T15:10:09Z",
      "authorized_date": "2023-09-27",
      "authorized_datetime": "2023-09-27T08:01:58Z",
      "location": {
        "address": null,
        "city": null,
        "region": null,
        "postal_code": null,
        "country": null,
        "lat": null,
        "lon": null,
        "store_number": null
      },
      "name": "Dd Doordash Burgerkin",
      "merchant_name": "Burger King",
      "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
      "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
      "website": "burgerking.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "online",
      "pending": true,
      "pending_transaction_id": null,
      "personal_finance_category": {
        "primary": "FOOD_AND_DRINK",
        "detailed": "FOOD_AND_DRINK_FAST_FOOD",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",
      "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
      "transaction_code": null,
      "transaction_type": "digital"
    },
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "account_owner": null,
      "amount": 72.1,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "check_number": null,
      "counterparties": [
        {
          "name": "Walmart",
          "type": "merchant",
          "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
          "website": "walmart.com",
          "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
          "confidence_level": "VERY_HIGH"
        }
      ],
      "date": "2023-09-24",
      "datetime": "2023-09-24T11:01:01Z",
      "authorized_date": "2023-09-22",
      "authorized_datetime": "2023-09-22T10:34:50Z",
      "location": {
        "address": "13425 Community Rd",
        "city": "Poway",
        "region": "CA",
        "postal_code": "92064",
        "country": "US",
        "lat": 32.959068,
        "lon": -117.037666,
        "store_number": "1700"
      },
      "name": "PURCHASE WM SUPERCENTER #1700",
      "merchant_name": "Walmart",
      "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
      "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
      "website": "walmart.com",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "in store",
      "pending": false,
      "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "personal_finance_category": {
        "primary": "GENERAL_MERCHANDISE",
        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
        "confidence_level": "VERY_HIGH"
      },
      "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "transaction_code": null,
      "transaction_type": "place"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "identity",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "institution_name": "Chase",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook",
    "auth_method": "INSTANT_AUTH"
  },
  "total_transactions": 1,
  "request_id": "45QSn"
}
```

\=\*=\*=\*=

#### /transactions/recurring/get 

#### Fetch recurring transaction streams 

The [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments.  
This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager.  
This endpoint can only be called on an Item that has already been initialized with Transactions (either during Link, by specifying it in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; or after Link, by calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) ).  
When using Recurring Transactions, for best results, make sure to use the [days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transactions-days-requested) parameter to request at least 180 days of history when initializing Items with Transactions. Once all historical transactions have been fetched, call [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) to receive the Recurring Transactions streams and subscribe to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook. To know when historical transactions have been fetched, if you are using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#SyncUpdatesAvailableWebhook-historical-update-complete) webhook and check that the `historical_update_complete` field in the payload is `true`. If using [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , listen for the [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) webhook.  
After the initial call, you can call [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook to be notified when new updates are available.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

**account\_ids** (\[string\])  
An optional list of account\_ids to retrieve for the Item. Retrieves all active accounts on item if no account\_ids are provided. Note: An error will be returned if a provided account\_id is not associated with the Item.

```javascript
const request: TransactionsGetRequest = {
  access_token: accessToken,
  account_ids : accountIds
};
try {
  const response = await client.transactionsRecurringGet(request);
  let inflowStreams = response.data.inflowStreams;
  let outflowStreams = response.data.outflowStreams;
  }
} catch((err) => {
  // handle error
}
```

#### Response fields and example 

**inflow\_streams** (\[object\])  
An array of depository transaction streams.

**inflow\_streams->account\_id** (string)  
The ID of the account to which the stream belongs

**inflow\_streams->stream\_id** (string)  
A unique id for the stream

**inflow\_streams->description** (string)  
A description of the transaction stream.

**inflow\_streams->merchant\_name** (nullable, string)  
The merchant associated with the transaction stream.

**inflow\_streams->first\_date** (string)  
The posted date of the earliest transaction in the stream. Format: date

**inflow\_streams->last\_date** (string)  
The posted date of the latest transaction in the stream. Format: date

**inflow\_streams->predicted\_next\_date** (nullable, string)  
The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: date

**inflow\_streams->frequency** (string)  
Describes the frequency of the transaction stream. WEEKLY: Assigned to a transaction stream that occurs approximately every week. BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks. SEMI\_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. MONTHLY: Assigned to a transaction stream that occurs approximately every month. ANNUALLY: Assigned to a transaction stream that occurs approximately every year. UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, ANNUALLY

**inflow\_streams->transaction\_ids** (\[string\])  
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.

**inflow\_streams->average\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**inflow\_streams->average\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**inflow\_streams->average\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**inflow\_streams->average\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**inflow\_streams->last\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**inflow\_streams->last\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**inflow\_streams->last\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**inflow\_streams->last\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**inflow\_streams->is\_active** (boolean)  
Indicates whether the transaction stream is still live.

**inflow\_streams->status** (string)  
The current status of the transaction stream. MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances). EARLY\_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY\_DETECTION. TOMBSTONED: A stream that was previously in the EARLY\_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date. UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable. Possible values: UNKNOWN, MATURE, EARLY\_DETECTION, TOMBSTONED

**inflow\_streams->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**inflow\_streams->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**inflow\_streams->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**inflow\_streams->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**inflow\_streams->is\_user\_modified** (deprecated, boolean)  
As the ability to modify transactions streams has been discontinued, this field will always be false.

**outflow\_streams** (\[object\])  
An array of expense transaction streams.

**outflow\_streams->account\_id** (string)  
The ID of the account to which the stream belongs

**outflow\_streams->stream\_id** (string)  
A unique id for the stream

**outflow\_streams->description** (string)  
A description of the transaction stream.

**outflow\_streams->merchant\_name** (nullable, string)  
The merchant associated with the transaction stream.

**outflow\_streams->first\_date** (string)  
The posted date of the earliest transaction in the stream. Format: date

**outflow\_streams->last\_date** (string)  
The posted date of the latest transaction in the stream. Format: date

**outflow\_streams->predicted\_next\_date** (nullable, string)  
The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: date

**outflow\_streams->frequency** (string)  
Describes the frequency of the transaction stream. WEEKLY: Assigned to a transaction stream that occurs approximately every week. BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks. SEMI\_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. MONTHLY: Assigned to a transaction stream that occurs approximately every month. ANNUALLY: Assigned to a transaction stream that occurs approximately every year. UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI\_MONTHLY, MONTHLY, ANNUALLY

**outflow\_streams->transaction\_ids** (\[string\])  
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.

**outflow\_streams->average\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**outflow\_streams->average\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**outflow\_streams->average\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**outflow\_streams->average\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**outflow\_streams->last\_amount** (object)  
Object with data pertaining to an amount on the transaction stream.

**outflow\_streams->last\_amount->amount** (number)  
Represents the numerical value of an amount. Format: double

**outflow\_streams->last\_amount->iso\_currency\_code** (nullable, string)  
The ISO-4217 currency code of the amount. Always null if unofficial\_currency\_code is non-null. See the currency code schema for a full listing of supported iso\_currency\_codes.

**outflow\_streams->last\_amount->unofficial\_currency\_code** (nullable, string)  
The unofficial currency code of the amount. Always null if iso\_currency\_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.

**outflow\_streams->is\_active** (boolean)  
Indicates whether the transaction stream is still live.

**outflow\_streams->status** (string)  
The current status of the transaction stream. MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances). EARLY\_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY\_DETECTION. TOMBSTONED: A stream that was previously in the EARLY\_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date. UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable. Possible values: UNKNOWN, MATURE, EARLY\_DETECTION, TOMBSTONED

**outflow\_streams->personal\_finance\_category** (nullable, object)  
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the taxonomy CSV file for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide.

**outflow\_streams->personal\_finance\_category->primary** (string)  
A high level category that communicates the broad category of the transaction.

**outflow\_streams->personal\_finance\_category->detailed** (string)  
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.

**outflow\_streams->personal\_finance\_category->confidence\_level** (nullable, string)  
A description of how confident we are that the provided categories accurately describe the transaction intent. VERY\_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: We don’t know the confidence level for this category.

**outflow\_streams->is\_user\_modified** (deprecated, boolean)  
As the ability to modify transactions streams has been discontinued, this field will always be false.

**updated\_datetime** (string)  
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time transaction streams for the given account were updated on Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "updated_datetime": "2022-05-01T00:00:00Z",
  "inflow_streams": [
    {
      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "category": null,
      "category_id": null,
      "description": "Platypus Payroll",
      "merchant_name": null,
      "personal_finance_category": {
        "primary": "INCOME",
        "detailed": "INCOME_WAGES",
        "confidence_level": "UNKNOWN"
      },
      "first_date": "2022-02-28",
      "last_date": "2022-04-30",
      "predicted_next_date": "2022-05-15",
      "frequency": "SEMI_MONTHLY",
      "transaction_ids": [
        "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw",
        "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL",
        "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd",
        "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK",
        "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF"
      ],
      "average_amount": {
        "amount": -800,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "last_amount": {
        "amount": -1000,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "is_active": true,
      "status": "MATURE",
      "is_user_modified": false
    }
  ],
  "outflow_streams": [
    {
      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd",
      "category": null,
      "category_id": null,
      "description": "ConEd Bill Payment",
      "merchant_name": "ConEd",
      "personal_finance_category": {
        "primary": "RENT_AND_UTILITIES",
        "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY",
        "confidence_level": "UNKNOWN"
      },
      "first_date": "2022-02-04",
      "last_date": "2022-05-02",
      "predicted_next_date": "2022-06-02",
      "frequency": "MONTHLY",
      "transaction_ids": [
        "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
        "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR",
        "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L",
        "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
      ],
      "average_amount": {
        "amount": 85,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "last_amount": {
        "amount": 100,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "is_active": true,
      "status": "MATURE",
      "is_user_modified": false
    },
    {
      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
      "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC",
      "category": null,
      "category_id": null,
      "description": "Costco Annual Membership",
      "merchant_name": "Costco",
      "personal_finance_category": {
        "primary": "GENERAL_MERCHANDISE",
        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
        "confidence_level": "UNKNOWN"
      },
      "first_date": "2022-01-23",
      "last_date": "2023-01-22",
      "predicted_next_date": "2024-01-22",
      "frequency": "ANNUALLY",
      "transaction_ids": [
        "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4",
        "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ"
      ],
      "average_amount": {
        "amount": 120,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "last_amount": {
        "amount": 120,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "is_active": true,
      "status": "MATURE",
      "is_user_modified": false
    }
  ],
  "request_id": "tbFyCEqkU775ZGG"
}
```

\=\*=\*=\*=

#### /transactions/refresh 

#### Refresh transaction data 

[/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) is an optional endpoint that initiates an on-demand extraction to fetch the newest transactions for an Item. The on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Transactions-enabled Item. The Item must already have Transactions added as a product in order to call [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) .  
If changes to transactions are discovered after calling [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , Plaid will fire a webhook: for [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) users, [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) will be fired if there are any transactions updated, added, or removed. For users of both [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) and [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) will be fired if any removed transactions are detected, and [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) will be fired if any new transactions are detected. New transactions can be fetched by calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .  
Note that the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint is not supported for Capital One (`ins_128026`) non-depository accounts and will result in a `PRODUCTS_NOT_SUPPORTED` error if called on an Item that contains only non-depository accounts from that institution.  
As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests.  
[/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) is offered as an optional add-on to Transactions and has a separate [fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

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

```javascript
const request: TransactionsRefreshRequest = {
  access_token: accessToken,
};
try {
  await plaidClient.transactionsRefresh(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "1vwmF5TBQwiqfwP"
}
```

\=\*=\*=\*=

#### /categories/get 

#### Get categories 

Send a request to the [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) endpoint to get detailed information on categories returned by Plaid. This endpoint does not require authentication.  
All implementations are recommended to use the newer `personal_finance_category` taxonomy instead of the older `category` taxonomy supported by this endpoint. The [personal\_finance\_category taxonomy CSV file](https://plaid.com/documents/transactions-personal-finance-category-taxonomy.csv) is available for download and is not accessible via API.

#### Request fields 

This endpoint takes an empty request body.

```javascript
try {
  const response = await plaidClient.categoriesGet({});
  const categories = response.data.categories;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**categories** (\[object\])  
An array of all of the transaction categories used by Plaid.

**categories->category\_id** (string)  
An identifying number for the category. category\_id is a Plaid-specific identifier and does not necessarily correspond to merchant category codes.

**categories->group** (string)  
place for physical transactions or special for other transactions such as bank charges.

**categories->hierarchy** (\[string\])  
A hierarchical array of the categories to which this category\_id belongs.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "categories": [
    {
      "category_id": "10000000",
      "group": "special",
      "hierarchy": [
        "Bank Fees"
      ]
    },
    {
      "category_id": "10001000",
      "group": "special",
      "hierarchy": [
        "Bank Fees",
        "Overdraft"
      ]
    },
    {
      "category_id": "12001000",
      "group": "place",
      "hierarchy": [
        "Community",
        "Animal Shelter"
      ]
    }
  ],
  "request_id": "ixTBLZGvhD4NnmB"
}
```

### Webhooks 

You can receive notifications via a webhook whenever there are new transactions associated with an Item, including when Plaid’s initial and historical transaction pull are completed. All webhooks related to transactions have a `webhook_type` of `TRANSACTIONS`.

\=\*=\*=\*=

#### SYNC\_UPDATES\_AVAILABLE 

Fired when an Item's transactions change. This can be due to any event resulting in new changes, such as an initial 30-day transactions fetch upon the initialization of an Item with transactions, the backfill of historical transactions that occurs shortly after, or when changes are populated from a regularly-scheduled transactions update job. It is recommended to listen for the `SYNC_UPDATES_AVAILABLE` webhook when using the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint. Note that when using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) the older webhooks `INITIAL_UPDATE`, `HISTORICAL_UPDATE`, `DEFAULT_UPDATE`, and `TRANSACTIONS_REMOVED`, which are intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , will also continue to be sent in order to maintain backwards compatibility. It is not necessary to listen for and respond to those webhooks when using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .  
After receipt of this webhook, the new changes can be fetched for the Item from [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .  
Note that to receive this webhook for an Item, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) must have been called at least once on that Item. This means that, unlike the `INITIAL_UPDATE` and `HISTORICAL_UPDATE` webhooks, it will not fire immediately upon Item creation. If [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is called on an Item that was _not_ initialized with Transactions, the webhook will fire twice: once the first 30 days of transactions data has been fetched, and a second time when all available historical transactions data has been fetched.  
This webhook will fire in the Sandbox environment as it would in Production. It can also be manually triggered in Sandbox by calling [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) .

#### Properties 

**webhook\_type** (string)  
TRANSACTIONS

**webhook\_code** (string)  
SYNC\_UPDATES\_AVAILABLE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**initial\_update\_complete** (boolean)  
Indicates if initial pull information (most recent 30 days of transaction history) is available.

**historical\_update\_complete** (boolean)  
Indicates if historical pull information (maximum transaction history requested, up to 2 years) is available.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "SYNC_UPDATES_AVAILABLE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "initial_update_complete": true,
  "historical_update_complete": false,
  "environment": "production"
}
```

\=\*=\*=\*=

#### RECURRING\_TRANSACTIONS\_UPDATE 

Fired when recurring transactions data is updated. This includes when a new recurring stream is detected or when a new transaction is added to an existing recurring stream. The `RECURRING_TRANSACTIONS_UPDATE` webhook will also fire when one or more attributes of the recurring stream changes, which is usually a result of the addition, update, or removal of transactions to the stream.  
After receipt of this webhook, the updated data can be fetched from [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) .

#### Properties 

**webhook\_type** (string)  
TRANSACTIONS

**webhook\_code** (string)  
RECURRING\_TRANSACTIONS\_UPDATE

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**account\_ids** (\[string\])  
A list of account\_ids for accounts that have new or updated recurring transactions data.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "RECURRING_TRANSACTIONS_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "account_ids": [
    "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
    "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff"
  ],
  "environment": "production"
}
```

\=\*=\*=\*=

#### INITIAL\_UPDATE 

Fired when an Item's initial transaction pull is completed. Once this webhook has been fired, transaction data for the most recent 30 days can be fetched for the Item. This webhook will also be fired if account selections for the Item are updated, with `new_transactions` set to the number of net new transactions pulled after the account selection update.  
This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead.

#### Properties 

**webhook\_type** (string)  
TRANSACTIONS

**webhook\_code** (string)  
INITIAL\_UPDATE

**error** (string)  
The error code associated with the webhook.

**new\_transactions** (number)  
The number of new transactions available.

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "INITIAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 19,
  "environment": "production"
}
```

\=\*=\*=\*=

#### HISTORICAL\_UPDATE 

Fired when an Item's historical transaction pull is completed and Plaid has prepared as much historical transaction data as possible for the Item. Once this webhook has been fired, transaction data beyond the most recent 30 days can be fetched for the Item. This webhook will also be fired if account selections for the Item are updated, with `new_transactions` set to the number of net new transactions pulled after the account selection update.  
This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead.

#### Properties 

**webhook\_type** (string)  
TRANSACTIONS

**webhook\_code** (string)  
HISTORICAL\_UPDATE

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**new\_transactions** (number)  
The number of new transactions available

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "HISTORICAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 231,
  "environment": "production"
}
```

\=\*=\*=\*=

#### DEFAULT\_UPDATE 

Fired when new transaction data is available for an Item. Plaid will typically check for new transaction data several times a day.  
This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead.

#### Properties 

**webhook\_type** (string)  
TRANSACTIONS

**webhook\_code** (string)  
DEFAULT\_UPDATE

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**new\_transactions** (number)  
The number of new transactions detected since the last time this webhook was fired.

**item\_id** (string)  
The item\_id of the Item the webhook relates to.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 3,
  "environment": "production"
}
```

\=\*=\*=\*=

#### TRANSACTIONS\_REMOVED 

Fired when transaction(s) for an Item are deleted. The deleted transaction IDs are included in the webhook payload. Plaid will typically check for deleted transaction data several times a day.  
This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead.

#### Properties 

**webhook\_type** (string)  
TRANSACTIONS

**webhook\_code** (string)  
TRANSACTIONS\_REMOVED

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**removed\_transactions** (\[string\])  
An array of transaction\_ids corresponding to the removed transactions

**item\_id** (string)  
The item\_id of the Item associated with this webhook, warning, or error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "TRANSACTIONS_REMOVED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "removed_transactions": [
    "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
    "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
  ],
  "error": null,
  "environment": "production"
}
```

---


# API - Account Linking | Plaid Docs

Transfer 
=========

#### API reference for Transfer account linking endpoints 

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

\=\*=\*=\*=

#### Account Linking 

| Account Linking |  |
| --- | --- |
| [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) | Determine RTP eligibility for a Plaid Item |
| [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | Create a transfer intent and invoke Transfer UI (Transfer UI only) |
| [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) | Retrieve information about a transfer intent (Transfer UI only) |
| [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) | Create an Item to use with Transfer from known account and routing numbers |

\=\*=\*=\*=

#### /transfer/capabilities/get 

#### Get RTP eligibility information of a transfer 

Use the [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) endpoint to determine the RTP eligibility information of an account to be used with Transfer. This endpoint works on all Transfer-capable Items, including those created by [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) .

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

**access\_token** (required, string)  
The Plaid access\_token for the account that will be debited or credited.

**account\_id** (required, string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

```javascript
const request: TransferCapabilitiesGetRequest = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
};


try {
  const response = await client.transferCapabilitiesGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**institution\_supported\_networks** (object)  
Contains the RTP and RfP network and types supported by the linked Item's institution.

**institution\_supported\_networks->rtp** (object)  
Contains the supported service types in RTP

**institution\_supported\_networks->rtp->credit** (boolean)  
When true, the linked Item's institution supports RTP credit transfer. Default: false

**institution\_supported\_networks->rfp** (object)  
Contains the supported service types in RfP

**institution\_supported\_networks->rfp->debit** (boolean)  
When true, the linked Item's institution supports RfP debit transfer. Default: false

**institution\_supported\_networks->rfp->max\_amount** (nullable, string)  
The maximum amount (decimal string with two digits of precision e.g. "10.00") for originating RfP transfers with the given institution.

**institution\_supported\_networks->rfp->iso\_currency\_code** (nullable, string)  
The currency of the max\_amount, e.g. "USD".

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "institution_supported_networks": {
    "rtp": {
      "credit": true
    },
    "rfp": {
      "debit": true
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/intent/create 

#### Create a transfer intent object to invoke the Transfer UI 

Use the [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) endpoint to generate a transfer intent object and invoke the Transfer UI.

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

**account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**mode** (required, string)  
The direction of the flow of transfer funds. PAYMENT: Transfers funds from an end user's account to your business account. DISBURSEMENT: Transfers funds from your business account to an end user's account. Possible values: PAYMENT, DISBURSEMENT

**network** (string)  
The network or rails used for the transfer. Defaults to same-day-ach. For transfers submitted using ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted using same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges. For transfers submitted using rtp, in the case that the account being credited does not support RTP, the transfer will be sent over ACH as long as an ach\_class is provided in the request. If RTP isn't supported by the account and no ach\_class is provided, the transfer will fail to be submitted. Possible values: ach, same-day-ach, rtpDefault: same-day-ach

**amount** (required, string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**description** (required, string)  
A description for the underlying transfer. Maximum of 15 characters. Min length: 1 Max length: 15

**ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**user** (required, object)  
The legal name and other information for the account holder.

**user->legal\_name** (required, string)  
The user's legal name.

**user->phone\_number** (string)  
The user's phone number. Phone number input may be validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
The address associated with the account holder.

**user->address->street** (string)  
The street number and name (i.e., "100 Market St.").

**user->address->city** (string)  
Ex. "San Francisco"

**user->address->region** (string)  
The state or province (e.g., "CA").

**user->address->postal\_code** (string)  
The postal code (e.g., "94103").

**user->address->country** (string)  
A two-letter country code (e.g., "US").

**metadata** (object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

```javascript
const request: TransferIntentCreateRequest = {
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  mode: 'PAYMENT'
  amount: '12.34',
  description: 'Desc',
  ach_class: 'ppd',
  origination_account_id: '9853defc-e703-463d-86b1-dc0607a45359',
  user: {
    legal_name: 'Anne Charleston',
  },
};


try {
  const response = await client.transferIntentCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transfer\_intent** (object)  
Represents a transfer intent within Transfer UI.

**transfer\_intent->id** (string)  
Plaid's unique identifier for the transfer intent object.

**transfer\_intent->created** (string)  
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**transfer\_intent->status** (string)  
The status of the transfer intent. PENDING: The transfer intent is pending. SUCCEEDED: The transfer intent was successfully created. FAILED: The transfer intent was unable to be created. Possible values: PENDING, SUCCEEDED, FAILED

**transfer\_intent->account\_id** (nullable, string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited. Returned only if account\_id was set on intent creation.

**transfer\_intent->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**transfer\_intent->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**transfer\_intent->mode** (string)  
The direction of the flow of transfer funds. PAYMENT: Transfers funds from an end user's account to your business account. DISBURSEMENT: Transfers funds from your business account to an end user's account. Possible values: PAYMENT, DISBURSEMENT

**transfer\_intent->network** (string)  
The network or rails used for the transfer. Defaults to same-day-ach. For transfers submitted using ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted using same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges. For transfers submitted using rtp, in the case that the account being credited does not support RTP, the transfer will be sent over ACH as long as an ach\_class is provided in the request. If RTP isn't supported by the account and no ach\_class is provided, the transfer will fail to be submitted. Possible values: ach, same-day-ach, rtpDefault: same-day-ach

**transfer\_intent->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**transfer\_intent->user** (object)  
The legal name and other information for the account holder.

**transfer\_intent->user->legal\_name** (string)  
The user's legal name.

**transfer\_intent->user->phone\_number** (nullable, string)  
The user's phone number.

**transfer\_intent->user->email\_address** (nullable, string)  
The user's email address.

**transfer\_intent->user->address** (nullable, object)  
The address associated with the account holder.

**transfer\_intent->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**transfer\_intent->user->address->city** (nullable, string)  
Ex. "San Francisco"

**transfer\_intent->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**transfer\_intent->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**transfer\_intent->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**transfer\_intent->description** (string)  
A description for the underlying transfer. Maximum of 8 characters.

**transfer\_intent->metadata** (nullable, object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**transfer\_intent->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfer_intent": {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
    "ach_class": "ppd",
    "amount": "12.34",
    "iso_currency_code": "USD",
    "created": "2020-08-06T17:27:15Z",
    "description": "Desc",
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "mode": "PAYMENT",
    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
    "status": "PENDING",
    "user": {
      "address": {
        "street": "100 Market Street",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94103",
        "country": "US"
      },
      "email_address": "acharleston@email.com",
      "legal_name": "Anne Charleston",
      "phone_number": "123-456-7890"
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/intent/get 

#### Retrieve more information about a transfer intent 

Use the [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) endpoint to retrieve more information about a transfer intent.

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

**transfer\_intent\_id** (required, string)  
Plaid's unique identifier for a transfer intent object.

```javascript
const request: TransferIntentGetRequest = {
  transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};


try {
  const response = await client.transferIntentGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transfer\_intent** (object)  
Represents a transfer intent within Transfer UI.

**transfer\_intent->id** (string)  
Plaid's unique identifier for a transfer intent object.

**transfer\_intent->created** (string)  
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**transfer\_intent->status** (string)  
The status of the transfer intent. PENDING: The transfer intent is pending. SUCCEEDED: The transfer intent was successfully created. FAILED: The transfer intent was unable to be created. Possible values: PENDING, SUCCEEDED, FAILED

**transfer\_intent->transfer\_id** (nullable, string)  
Plaid's unique identifier for the transfer created through the UI. Returned only if the transfer was successfully created. Null value otherwise.

**transfer\_intent->failure\_reason** (nullable, object)  
The reason for a failed transfer intent. Returned only if the transfer intent status is failed. Null otherwise.

**transfer\_intent->failure\_reason->error\_type** (string)  
A broad categorization of the error.

**transfer\_intent->failure\_reason->error\_code** (string)  
A code representing the reason for a failed transfer intent (i.e., an API error or the authorization being declined).

**transfer\_intent->failure\_reason->error\_message** (string)  
A human-readable description of the code associated with a failed transfer intent.

**transfer\_intent->authorization\_decision** (nullable, string)  
A decision regarding the proposed transfer. APPROVED – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision\_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update mode to re-authenticate your user when decision\_rationale.code is ITEM\_LOGIN\_REQUIRED). Refer to the code field in the decision\_rationale object for details. DECLINED – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision\_rationale object for details. Possible values: APPROVED, DECLINED

**transfer\_intent->authorization\_decision\_rationale** (nullable, object)  
The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.

**transfer\_intent->authorization\_decision\_rationale->code** (string)  
A code representing the rationale for approving or declining the proposed transfer. If the rationale\_code is null, the transfer passed the authorization check. Any non-null value for an approved transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved transfer are: MANUALLY\_VERIFIED\_ITEM – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. ITEM\_LOGIN\_REQUIRED – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting transfer.authorization\_id in the request to /link/token/create. MIGRATED\_ACCOUNT\_ITEM - Item created via /transfer/migrate\_account endpoint, limited information available. ERROR – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was declined: NSF – Transaction likely to result in a return due to insufficient funds. RISK - Transaction is high-risk. TRANSFER\_LIMIT\_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying description field to understand which limit has been reached. Possible values: NSF, RISK, TRANSFER\_LIMIT\_REACHED, MANUALLY\_VERIFIED\_ITEM, ITEM\_LOGIN\_REQUIRED, PAYMENT\_PROFILE\_LOGIN\_REQUIRED, ERROR, MIGRATED\_ACCOUNT\_ITEM, null

**transfer\_intent->authorization\_decision\_rationale->description** (string)  
A human-readable description of the code associated with a transfer approval or transfer decline.

**transfer\_intent->account\_id** (nullable, string)  
The Plaid account\_id for the account that will be debited or credited. Returned only if account\_id was set on intent creation.

**transfer\_intent->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**transfer\_intent->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**transfer\_intent->mode** (string)  
The direction of the flow of transfer funds. PAYMENT: Transfers funds from an end user's account to your business account. DISBURSEMENT: Transfers funds from your business account to an end user's account. Possible values: PAYMENT, DISBURSEMENT

**transfer\_intent->network** (string)  
The network or rails used for the transfer. Defaults to same-day-ach. For transfers submitted using ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted using same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges. For transfers submitted using rtp, in the case that the account being credited does not support RTP, the transfer will be sent over ACH as long as an ach\_class is provided in the request. If RTP isn't supported by the account and no ach\_class is provided, the transfer will fail to be submitted. Possible values: ach, same-day-ach, rtpDefault: same-day-ach

**transfer\_intent->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**transfer\_intent->user** (object)  
The legal name and other information for the account holder.

**transfer\_intent->user->legal\_name** (string)  
The user's legal name.

**transfer\_intent->user->phone\_number** (nullable, string)  
The user's phone number.

**transfer\_intent->user->email\_address** (nullable, string)  
The user's email address.

**transfer\_intent->user->address** (nullable, object)  
The address associated with the account holder.

**transfer\_intent->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**transfer\_intent->user->address->city** (nullable, string)  
Ex. "San Francisco"

**transfer\_intent->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**transfer\_intent->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**transfer\_intent->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**transfer\_intent->description** (string)  
A description for the underlying transfer. Maximum of 8 characters.

**transfer\_intent->metadata** (nullable, object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**transfer\_intent->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfer_intent": {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
    "ach_class": "ppd",
    "amount": "12.34",
    "iso_currency_code": "USD",
    "authorization_decision": "APPROVED",
    "authorization_decision_rationale": null,
    "created": "2019-12-09T17:27:15Z",
    "description": "Desc",
    "failure_reason": null,
    "guarantee_decision": null,
    "guarantee_decision_rationale": null,
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "mode": "DISBURSEMENT",
    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
    "status": "SUCCEEDED",
    "transfer_id": "590ecd12-1dcc-7eae-4ad6-c28d1ec90df2",
    "user": {
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "California",
        "postal_code": "94053",
        "country": "US"
      },
      "email_address": "acharleston@email.com",
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128"
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/migrate\_account 

#### Migrate account into Transfers 

As an alternative to adding Items via Link, you can also use the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint to migrate previously-verified account and routing numbers to Plaid Items. This endpoint is also required when adding an Item for use with wire transfers; if you intend to create wire transfers on this account, you must provide `wire_routing_number`. Note that Items created in this way are not compatible with endpoints for other products, such as [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) , and can only be used with Transfer endpoints. If you require access to other endpoints, create the Item through Link instead. Access to [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) is not enabled by default; to obtain access, contact your Plaid Account Manager or [Support](https://dashboard.plaid.com/support) .

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

**account\_number** (required, string)  
The user's account number.

**routing\_number** (required, string)  
The user's routing number.

**wire\_routing\_number** (string)  
The user's wire transfer routing number. This is the ABA number; for some institutions, this may differ from the ACH number used in routing\_number. This field must be set for the created item to be eligible for wire transfers.

**account\_type** (required, string)  
The type of the bank account (checking or savings).

```javascript
const request: TransferMigrateAccountRequest = {
  account_number: '100000000',
  routing_number: '121122676',
  account_type: 'checking',
};
try {
  const response = await plaidClient.transferMigrateAccount(request);
  const access_token = response.data.access_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**access\_token** (string)  
The Plaid access\_token for the newly created Item.

**account\_id** (string)  
The Plaid account\_id for the newly created Item.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0",
  "account_id": "zvyDgbeeDluZ43AJP6m5fAxDlgoZXDuoy5gjN",
  "request_id": "mdqfuVxeoza6mhu"
}
```

---


# API - Transfer | Plaid Docs

Transfer 
=========

#### API reference for Transfer endpoints and webhooks 

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

| Initiating Transfers |  |
| --- | --- |
| [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | Create a transfer authorization |
| [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) | Cancel a transfer authorization |
| [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | Create a transfer |
| [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | Cancel a transfer |

| Reading Transfers |  |
| --- | --- |
| [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) | Retrieve information about a transfer |
| [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) | Retrieve a list of transfers and their statuses |
| [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) | Retrieve a list of transfer events |
| [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) | Sync transfer events |
| [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) | Retrieve information about a sweep |
| [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) | Retrieve a list of sweeps |

| Account Linking |  |
| --- | --- |
| [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) | Determine RTP eligibility for a Plaid Item |
| [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | Create a transfer intent and invoke Transfer UI (Transfer UI only) |
| [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) | Retrieve information about a transfer intent (Transfer UI only) |
| [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) | Create an Item to use with Transfer from known account and routing numbers |

| Recurring Transfers |  |
| --- | --- |
| [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | Create a recurring transfer |
| [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) | Cancel a recurring transfer |
| [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) | Retrieve information about a recurring transfer |
| [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) | Retrieve a list of recurring transfers |

| Refunds |  |
| --- | --- |
| [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | Create a refund for a transfer |
| [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) | Cancel a refund |
| [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) | Retrieve information about a refund |

| Platform Payments |  |
| --- | --- |
| [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) | Create a new originator |
| [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) | Get the status of an originator's onboarding |
| [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) | Get the status of all originators' onboarding |
| [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) | Create a new funding account for an originator |
| [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) | Generate a Plaid-hosted onboarding UI URL |

| Plaid Ledger |  |
| --- | --- |
| [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) | Deposit funds into a ledger balance held with Plaid |
| [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) | Move available balance between platform and its originator |
| [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) | Retrieve information about the ledger balance held with Plaid |
| [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) | Withdraw funds from a ledger balance held with Plaid |
| [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) | Retrieve a list of ledger balance events |

| Program Metrics |  |
| --- | --- |
| [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) | Get transfer product usage metrics |
| [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) | Get transfer product configuration |

| Sandbox |  |
| --- | --- |
| [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) | Simulate a transfer event |
| [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) | Simulate a refund event |
| [/sandbox/transfer/sweep/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersweepsimulate) | Simulate creating a sweep |
| [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) | Simulate a transfer webhook |
| [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) | Simulate a deposit sweep event |
| [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) | Simulate converting pending balance into available balance |
| [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) | Simulate a withdrawal sweep event |
| [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) | Create a test clock |
| [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) | Advance a test clock |
| [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) | Retrieve information about a test clock |
| [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) | Retrieve a list of test clocks |

| Webhooks |  |
| --- | --- |
| [TRANSFER\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer_events_update) | New transfer events available |
| [RECURRING\_CANCELLED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_cancelled) | A recurring transfer has been cancelled by Plaid |
| [RECURRING\_NEW\_TRANSFER](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) | A new transfer of a recurring transfer has been originated |
| [RECURRING\_TRANSFER\_SKIPPED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_transfer_skipped) | An instance of a scheduled recurring transfer could not be created |

---


# API - Initiating Transfers | Plaid Docs

Initiating transfers 
=====================

#### API reference for Transfer initiation endpoints 

For how-to guidance, see the [Transfer creation documentation](https://plaid.com/docs/transfer/creating-transfers/index.html.md) .

| Initiating Transfers |  |
| --- | --- |
| [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | Create a transfer authorization |
| [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) | Cancel a transfer authorization |
| [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | Create a transfer |
| [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | Cancel a transfer |

\=\*=\*=\*=

#### /transfer/authorization/create 

#### Create a transfer authorization 

Use the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) endpoint to authorize a transfer. This endpoint must be called prior to calling [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . The transfer authorization will expire if not used after one hour. (You can contact your account manager to change the default authorization lifetime.)  
There are four possible outcomes to calling this endpoint:  
\- If the `authorization.decision` in the response is `declined`, the proposed transfer has failed the risk check and you cannot proceed with the transfer.  
\- If the `authorization.decision` is `user_action_required`, additional user input is needed, usually to fix a broken bank connection, before Plaid can properly assess the risk. You need to launch Link in update mode to complete the required user action. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to get a new Link token, instead of providing `access_token` in the request, you should set [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) as the `authorization.id`. After the Link flow is completed, you may re-attempt the authorization.  
\- If the `authorization.decision` is `approved`, and the `authorization.rationale_code` is `null`, the transfer has passed the risk check and you can proceed to call [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) .  
\- If the `authorization.decision` is `approved` and the `authorization.rationale_code` is non-`null`, the risk check could not be run: you may proceed with the transfer, but should perform your own risk evaluation. For more details, see the response schema.  
In Plaid's Sandbox environment the decisions will be returned as follows:  
\- To approve a transfer with `null` rationale code, make an authorization request with an `amount` less than the available balance in the account.  
\- To approve a transfer with the rationale code `MANUALLY_VERIFIED_ITEM`, create an Item in Link through the [Same Day Micro-deposits flow](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) .  
\- To get an authorization decision of `user_action_required`, [reset the login for an Item](https://plaid.com/docs/sandbox/index.html.md#item_login_required) .  
\- To decline a transfer with the rationale code `NSF`, the available balance on the account must be less than the authorization `amount`. See [Create Sandbox test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) for details on how to customize data in Sandbox.  
\- To decline a transfer with the rationale code `RISK`, the available balance on the account must be exactly $0. See [Create Sandbox test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) for details on how to customize data in Sandbox.

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

**access\_token** (required, string)  
The Plaid access\_token for the account that will be debited or credited.

**account\_id** (required, string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**ledger\_id** (string)  
Specify which ledger balance should be used to fund the transfer. You can find a list of ledger\_ids in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance.

**type** (required, string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**network** (required, string)  
The network or rails used for the transfer. For transfers submitted as ach or same-day-ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID\_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create. Wire transfers are currently in early availability. To request access to wire as a payment network, contact your Account Manager. For transfers submitted as wire, the type must be credit; wire debits are not supported. The cutoff to submit a wire payment is 4:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: ach, same-day-ach, rtp, wire

**amount** (required, string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**wire\_details** (object)  
Information specific to wire transfers.

**wire\_details->message\_to\_beneficiary** (string)  
Additional information from the wire originator to the beneficiary. Max 140 characters.

**wire\_details->wire\_return\_fee** (string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**user** (required, object)  
The legal name and other information for the account holder. If the account has multiple account holders, provide the information for the account holder on whose behalf the authorization is being requested. The user.legal\_name field is required. Other fields are not currently used and are present to support planned future functionality.

**user->legal\_name** (required, string)  
The user's legal name. If the user is a business, provide the business name.

**user->phone\_number** (string)  
The user's phone number.

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
The address associated with the account holder.

**user->address->street** (string)  
The street number and name (i.e., "100 Market St.").

**user->address->city** (string)  
Ex. "San Francisco"

**user->address->region** (string)  
The state or province (e.g., "CA").

**user->address->postal\_code** (string)  
The postal code (e.g., "94103").

**user->address->country** (string)  
A two-letter country code (e.g., "US").

**device** (object)  
Information about the device being used to initiate the authorization. These fields are not currently incorporated into the risk check.

**device->ip\_address** (string)  
The IP address of the device being used to initiate the authorization.

**device->user\_agent** (string)  
The user agent of the device being used to initiate the authorization.

**iso\_currency\_code** (string)  
The currency of the transfer amount. The default value is "USD".

**idempotency\_key** (string)  
A random key provided by the client, per unique authorization, which expires after 48 hours. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an authorization fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization is created. Idempotency does not apply to authorizations whose decisions are user\_action\_required. Therefore you may re-attempt the authorization after completing the required user action without changing idempotency\_key. This idempotency key expires after 48 hours, after which the same key can be reused. Failure to provide this key may result in duplicate charges. Max length: 50

**user\_present** (boolean)  
If the end user is initiating the specific transfer themselves via an interactive UI, this should be true; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false. This field is not currently used and is present to support planned future functionality.

**originator\_client\_id** (string)  
The Plaid client ID that is the originator of this transfer. Only needed if creating transfers on behalf of another client as a Platform customer.

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. This field may only be used when using sandbox environment. If provided, the authorization is created at the virtual\_time on the provided test clock.

**ruleset\_key** (string)  
The key of the Ruleset for the transaction. This feature is currently in closed beta; to request access, contact your account manager.

```javascript
const request: TransferAuthorizationCreateRequest = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  type: 'debit',
  network: 'ach',
  amount: '12.34',
  ach_class: 'ppd',
  user: {
    legal_name: 'Anne Charleston',
  },
};


try {
  const response = await client.transferAuthorizationCreate(request);
  const authorizationId = response.data.authorization.id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**authorization** (object)  
Contains the authorization decision for a proposed transfer.

**authorization->id** (string)  
Plaid’s unique identifier for a transfer authorization.

**authorization->created** (string)  
The datetime representing when the authorization was created, in the format 2006-01-02T15:04:05Z. Format: date-time

**authorization->decision** (string)  
A decision regarding the proposed transfer. approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision\_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended. Refer to the code field in the decision\_rationale object for details. declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision\_rationale object for details. user\_action\_required – An action is required before Plaid can assess the transfer risk and make a decision. The most common scenario is to update authentication for an Item. To complete the required action, initialize Link by setting transfer.authorization\_id in the request of /link/token/create. After Link flow is completed, you may re-attempt the authorization request. Possible values: approved, declined, user\_action\_required

**authorization->decision\_rationale** (nullable, object)  
The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.

**authorization->decision\_rationale->code** (string)  
A code representing the rationale for approving or declining the proposed transfer. If the rationale\_code is null, the transfer passed the authorization check. Any non-null value for an approved transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved transfer are: MANUALLY\_VERIFIED\_ITEM – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. ITEM\_LOGIN\_REQUIRED – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting transfer.authorization\_id in the request to /link/token/create. MIGRATED\_ACCOUNT\_ITEM - Item created via /transfer/migrate\_account endpoint, limited information available. ERROR – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was declined: NSF – Transaction likely to result in a return due to insufficient funds. RISK - Transaction is high-risk. TRANSFER\_LIMIT\_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying description field to understand which limit has been reached. Possible values: NSF, RISK, TRANSFER\_LIMIT\_REACHED, MANUALLY\_VERIFIED\_ITEM, ITEM\_LOGIN\_REQUIRED, PAYMENT\_PROFILE\_LOGIN\_REQUIRED, ERROR, MIGRATED\_ACCOUNT\_ITEM, null

**authorization->decision\_rationale->description** (string)  
A human-readable description of the code associated with a transfer approval or transfer decline.

**authorization->proposed\_transfer** (object)  
Details regarding the proposed transfer.

**authorization->proposed\_transfer->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**authorization->proposed\_transfer->account\_id** (string)  
The Plaid account\_id for the account that will be debited or credited.

**authorization->proposed\_transfer->funding\_account\_id** (nullable, string)  
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

**authorization->proposed\_transfer->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**authorization->proposed\_transfer->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**authorization->proposed\_transfer->user** (object)  
The legal name and other information for the account holder.

**authorization->proposed\_transfer->user->legal\_name** (string)  
The user's legal name.

**authorization->proposed\_transfer->user->phone\_number** (nullable, string)  
The user's phone number.

**authorization->proposed\_transfer->user->email\_address** (nullable, string)  
The user's email address.

**authorization->proposed\_transfer->user->address** (nullable, object)  
The address associated with the account holder.

**authorization->proposed\_transfer->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**authorization->proposed\_transfer->user->address->city** (nullable, string)  
Ex. "San Francisco"

**authorization->proposed\_transfer->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**authorization->proposed\_transfer->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**authorization->proposed\_transfer->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**authorization->proposed\_transfer->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**authorization->proposed\_transfer->network** (string)  
The network or rails used for the transfer.

**authorization->proposed\_transfer->wire\_details** (nullable, object)  
Information specific to wire transfers.

**authorization->proposed\_transfer->wire\_details->message\_to\_beneficiary** (nullable, string)  
Additional information from the wire originator to the beneficiary. Max 140 characters.

**authorization->proposed\_transfer->wire\_details->wire\_return\_fee** (nullable, string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**authorization->proposed\_transfer->iso\_currency\_code** (string)  
The currency of the transfer amount. The default value is "USD".

**authorization->proposed\_transfer->originator\_client\_id** (nullable, string)  
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a Platform customer.

**authorization->proposed\_transfer->credit\_funds\_source** (deprecated, nullable, string)  
This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers. sweep - Sweep funds from your funding account prefunded\_rtp\_credits - Use your prefunded RTP credit balance with Plaid prefunded\_ach\_credits - Use your prefunded ACH credit balance with Plaid Possible values: sweep, prefunded\_rtp\_credits, prefunded\_ach\_credits, null

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "authorization": {
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "created": "2020-08-06T17:27:15Z",
    "decision": "approved",
    "decision_rationale": null,
    "guarantee_decision": null,
    "guarantee_decision_rationale": null,
    "payment_risk": null,
    "proposed_transfer": {
      "ach_class": "ppd",
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
      "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
      "type": "credit",
      "user": {
        "legal_name": "Anne Charleston",
        "phone_number": "510-555-0128",
        "email_address": "acharleston@email.com",
        "address": {
          "street": "123 Main St.",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94053",
          "country": "US"
        }
      },
      "amount": "12.34",
      "network": "ach",
      "iso_currency_code": "USD",
      "origination_account_id": "",
      "originator_client_id": null,
      "credit_funds_source": "sweep"
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/authorization/cancel 

#### Cancel a transfer authorization 

Use the [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) endpoint to cancel a transfer authorization. A transfer authorization is eligible for cancellation if it has not yet been used to create a transfer.

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

**authorization\_id** (required, string)  
Plaid’s unique identifier for a transfer authorization.

```javascript
const request: TransferAuthorizationCancelRequest = {
  authorization_id: '123004561178933',
};
try {
  const response = await plaidClient.transferAuthorizationCancel(request);
  const request_id = response.data.request_id;
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/create 

#### Create a transfer 

Use the [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) endpoint to initiate a new transfer. This endpoint is retryable and idempotent; if a transfer with the provided `transfer_id` has already been created, it will return the transfer details without creating a new transfer. A transfer may still be created if a 500 error is returned; to detect this scenario, use [Transfer events](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) .

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

**access\_token** (required, string)  
The Plaid access\_token for the account that will be debited or credited.

**account\_id** (required, string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**authorization\_id** (required, string)  
Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.

**amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**description** (required, string)  
The transfer description, maximum of 15 characters. Should represent why the money is moving, not your company name. For recommendations on setting the description field to avoid ACH returns, see Description field recommendations. If reprocessing a returned transfer, the description field must be "Retry 1" or "Retry 2". You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code R01 or R09 may be retried. Max length: 15

**metadata** (object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. This field may only be used when using sandbox environment. If provided, the transfer is created at the virtual\_time on the provided test\_clock.

**facilitator\_fee** (string)  
The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the transfer.amount.

```javascript
const request: TransferCreateRequest = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  description: 'payment',
  authorization_id: '231h012308h3101z21909sw',
};
try {
  const response = await client.transferCreate(request);
  const transfer = response.data.transfer;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transfer** (object)  
Represents a transfer within the Transfers API.

**transfer->id** (string)  
Plaid’s unique identifier for a transfer.

**transfer->authorization\_id** (string)  
Plaid’s unique identifier for a transfer authorization.

**transfer->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**transfer->account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**transfer->funding\_account\_id** (nullable, string)  
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

**transfer->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfer->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**transfer->user** (object)  
The legal name and other information for the account holder.

**transfer->user->legal\_name** (string)  
The user's legal name.

**transfer->user->phone\_number** (nullable, string)  
The user's phone number.

**transfer->user->email\_address** (nullable, string)  
The user's email address.

**transfer->user->address** (nullable, object)  
The address associated with the account holder.

**transfer->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**transfer->user->address->city** (nullable, string)  
Ex. "San Francisco"

**transfer->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**transfer->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**transfer->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**transfer->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**transfer->description** (string)  
The description of the transfer.

**transfer->created** (string)  
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**transfer->status** (string)  
The status of the transfer. pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: The transfer was successfully completed by the payment network. Note that funds from received debits are not available to be moved out of the Ledger until the transfer reaches funds\_available status. For credit transactions, settled means the funds have been delivered to the receiving bank account. This is the terminal state of a successful credit transfer. funds\_available: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) This is the terminal state of a successful debit transfer. cancelled: The transfer was cancelled by the client. This is the terminal state of a cancelled transfer. failed: The transfer failed, no funds were moved. This is the terminal state of a failed transfer. returned: A posted transfer was returned. This is the terminal state of a returned transfer. Possible values: pending, posted, settled, funds\_available, cancelled, failed, returned

**transfer->sweep\_status** (nullable, string)  
The status of the sweep for the transfer. unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept\_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return\_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept) Possible values: null, unswept, swept, swept\_settled, return\_swept

**transfer->network** (string)  
The network or rails used for the transfer. For transfers submitted as ach or same-day-ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID\_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create. Wire transfers are currently in early availability. To request access to wire as a payment network, contact your Account Manager. For transfers submitted as wire, the type must be credit; wire debits are not supported. The cutoff to submit a wire payment is 4:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: ach, same-day-ach, rtp, wire

**transfer->wire\_details** (nullable, object)  
Information specific to wire transfers.

**transfer->wire\_details->message\_to\_beneficiary** (nullable, string)  
Additional information from the wire originator to the beneficiary. Max 140 characters.

**transfer->wire\_details->wire\_return\_fee** (nullable, string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**transfer->cancellable** (boolean)  
When true, you can still cancel this transfer.

**transfer->failure\_reason** (nullable, object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**transfer->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfer->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**transfer->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfer->metadata** (nullable, object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**transfer->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**transfer->standard\_return\_window** (nullable, string)  
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD. Format: date

**transfer->unauthorized\_return\_window** (nullable, string)  
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD. Format: date

**transfer->expected\_settlement\_date** (nullable, string)  
The date when settlement will occur between Plaid and the receiving bank (RDFI). For ACH debits, this is the date funds will be pulled from the bank account being debited. For ACH credits, this is the date funds will be delivered to the bank account being credited. Only set for ACH transfers; null for non-ACH transfers. This will be of the form YYYY-MM-DD. Format: date

**transfer->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a transfer will be made available and can be withdrawn from the associated ledger balance, assuming the debit does not return before this date. If the transfer does return before this date, this field will be null. Only applies to debit transfers. This will be of the form YYYY-MM-DD. Format: date

**transfer->originator\_client\_id** (nullable, string)  
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a Platform customer.

**transfer->refunds** (\[object\])  
A list of refunds associated with this transfer.

**transfer->refunds->id** (string)  
Plaid’s unique identifier for a refund.

**transfer->refunds->transfer\_id** (string)  
The ID of the transfer to refund.

**transfer->refunds->amount** (string)  
The amount of the refund (decimal string with two digits of precision e.g. "10.00").

**transfer->refunds->status** (string)  
The status of the refund. pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned. Possible values: pending, posted, cancelled, failed, settled, returned

**transfer->refunds->failure\_reason** (nullable, object)  
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

**transfer->refunds->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the refund status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfer->refunds->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors. This field is deprecated in favor of the more versatile failure\_code, which encompasses non-ACH failure codes as well.

**transfer->refunds->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfer->refunds->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfer->refunds->created** (string)  
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**transfer->refunds->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**transfer->recurring\_transfer\_id** (nullable, string)  
The id of the recurring transfer if this transfer belongs to a recurring transfer.

**transfer->expected\_sweep\_settlement\_schedule** (\[object\])  
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.

**transfer->expected\_sweep\_settlement\_schedule->sweep\_settlement\_date** (string)  
The settlement date of a sweep for this transfer. Format: date

**transfer->expected\_sweep\_settlement\_schedule->swept\_settled\_amount** (string)  
The accumulated amount that has been swept by sweep\_settlement\_date.

**transfer->credit\_funds\_source** (deprecated, nullable, string)  
This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers. sweep - Sweep funds from your funding account prefunded\_rtp\_credits - Use your prefunded RTP credit balance with Plaid prefunded\_ach\_credits - Use your prefunded ACH credit balance with Plaid Possible values: sweep, prefunded\_rtp\_credits, prefunded\_ach\_credits, null

**transfer->facilitator\_fee** (string)  
The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the transfer.amount.

**transfer->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfer": {
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
    "ach_class": "ppd",
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
    "type": "credit",
    "user": {
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128",
      "email_address": "acharleston@email.com",
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94053",
        "country": "US"
      }
    },
    "amount": "12.34",
    "description": "payment",
    "created": "2020-08-06T17:27:15Z",
    "refunds": [],
    "status": "pending",
    "network": "ach",
    "cancellable": true,
    "guarantee_decision": null,
    "guarantee_decision_rationale": null,
    "failure_reason": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "origination_account_id": "",
    "iso_currency_code": "USD",
    "standard_return_window": "2023-08-07",
    "unauthorized_return_window": "2023-10-07",
    "expected_settlement_date": "2023-08-04",
    "originator_client_id": "569ed2f36b3a3a021713abc1",
    "recurring_transfer_id": null,
    "credit_funds_source": "sweep",
    "facilitator_fee": "1.23",
    "network_trace_id": null
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/cancel 

#### Cancel a transfer 

Use the [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) endpoint to cancel a transfer. A transfer is eligible for cancellation if the `cancellable` property returned by [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) is `true`.

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

**transfer\_id** (required, string)  
Plaid’s unique identifier for a transfer.

**reason\_code** (string)  
Specifies the reason for cancelling transfer. This is required for RfP transfers, and will be ignored for other networks. "AC03" - Invalid Creditor Account Number "AM09" - Incorrect Amount "CUST" - Requested By Customer - Cancellation requested "DUPL" - Duplicate Payment "FRAD" - Fraudulent Payment - Unauthorized or fraudulently induced "TECH" - Technical Problem - Cancellation due to system issues "UPAY" - Undue Payment - Payment was made through another channel "AC14" - Invalid or Missing Creditor Account Type "AM06" - Amount Too Low "BE05" - Unrecognized Initiating Party "FOCR" - Following Refund Request "MS02" - No Specified Reason - Customer "MS03" - No Specified Reason - Agent "RR04" - Regulatory Reason "RUTA" - Return Upon Unable To Apply Possible values: AC03, AM09, CUST, DUPL, FRAD, TECH, UPAY, AC14, AM06, BE05, FOCR, MS02, MS03, RR04, RUTA

```javascript
const request: TransferCancelRequest = {
  transfer_id: '123004561178933',
};
try {
  const response = await plaidClient.transferCancel(request);
  const request_id = response.data.request_id;
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "saKrIBuEB9qJZno"
}
```

---


# API - Plaid Ledger | Plaid Docs

Plaid Ledger 
=============

#### API reference for Plaid Ledger 

For how-to guidance, see the [Ledger documentation](https://plaid.com/docs/transfer/flow-of-funds/index.html.md) .

| Plaid Ledger |  |
| --- | --- |
| [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) | Deposit funds into a ledger balance held with Plaid |
| [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) | Move available balance between platform and its originator |
| [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) | Retrieve information about the ledger balance held with Plaid |
| [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) | Withdraw funds from a ledger balance held with Plaid |
| [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) | Retrieve a list of ledger balance events |

\=\*=\*=\*=

#### /transfer/ledger/deposit 

#### Deposit funds into a Plaid Ledger balance 

Use the [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) endpoint to deposit funds into Plaid Ledger.

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

**originator\_client\_id** (string)  
Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to payout or collect funds. Only applicable for Platform customers. Do not include if you’re paying out to yourself.

**funding\_account\_id** (string)  
Specify which funding account to use. Customers can find a list of funding\_account\_ids in the Accounts page of the Plaid Dashboard, under the "Account ID" column. If this field is left blank, the funding account associated with the specified Ledger will be used. If an originator\_client\_id is specified, the funding\_account\_id must belong to the specified originator.

**ledger\_id** (string)  
Specify which ledger balance to deposit to. Customers can find a list of ledger\_ids in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance.

**amount** (required, string)  
A positive amount of how much will be deposited into ledger (decimal string with two digits of precision e.g. "5.50").

**description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. Max length: 10

**idempotency\_key** (required, string)  
A unique key provided by the client, per unique ledger deposit. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger deposit fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single deposit is created. Max length: 50

**network** (required, string)  
The ACH networks used for the funds flow. For requests submitted as either ach or same-day-ach the cutoff for Same Day ACH is 3:30 PM Eastern Time and the cutoff for Standard ACH transfers is 8:30 PM Eastern Time. It is recommended to submit a request at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any request that is indicated as same-day-ach and that misses the Same Day ACH cutoff, but is submitted in time for the Standard ACH cutoff, will be sent over Standard ACH rails and will not incur same-day charges. Possible values: ach, same-day-ach

```javascript
const request: TransferLedgerDepositRequest = {
  amount: '12.34',
  network: 'ach',
  idempotency_key: 'test_deposit_abc',
  description: 'deposit',
};
try {
  const response = await client.transferLedgerDeposit(request);
  const sweep = response.data.sweep;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**sweep** (object)  
Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type swept or return\_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep\_id. swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return\_swept events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the swept and return\_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.

**sweep->id** (string)  
Identifier of the sweep.

**sweep->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**sweep->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**sweep->created** (string)  
The datetime when the sweep occurred, in RFC 3339 format. Format: date-time

**sweep->amount** (string)  
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

**sweep->iso\_currency\_code** (string)  
The currency of the sweep, e.g. "USD".

**sweep->settled** (nullable, string)  
The date when the sweep settled, in the YYYY-MM-DD format. Format: date

**sweep->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: date

**sweep->status** (nullable, string)  
The status of a sweep transfer "pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled. This is the terminal state of a successful credit sweep. "returned" - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. "funds\_available" - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. "failed" - The sweep has failed. This is the terminal state of a failed sweep. Possible values: pending, posted, settled, funds\_available, returned, failed, null

**sweep->trigger** (nullable, string)  
The trigger of the sweep "manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance\_threshold" - The sweep is created by balance threshold setting "automatic\_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: manual, incoming, balance\_threshold, automatic\_aggregate

**sweep->description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

**sweep->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**sweep->failure\_reason** (nullable, object)  
The failure reason if the status for a sweep is "failed" or "returned". Null value otherwise.

**sweep->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the sweep status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**sweep->failure\_reason->description** (nullable, string)  
A human-readable description of the reason for the failure or reversal.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "sweep": {
    "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
    "created": "2020-08-06T17:27:15Z",
    "amount": "-12.34",
    "iso_currency_code": "USD",
    "settled": null,
    "status": "pending",
    "trigger": "manual",
    "description": "deposit",
    "network_trace_id": null
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/ledger/distribute 

#### Move available balance between ledgers 

Use the [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) endpoint to move available balance between ledgers, if you have multiple. If you’re a platform, you can move funds between one of your ledgers and one of your customer’s ledger.

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

**from\_ledger\_id** (required, string)  
The Ledger to pull money from.

**to\_ledger\_id** (required, string)  
The Ledger to credit money to.

**amount** (required, string)  
The amount to move (decimal string with two digits of precision e.g. "10.00"). Amount must be positive.

**idempotency\_key** (required, string)  
A unique key provided by the client, per unique ledger distribute. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger distribute fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single distribute is created. Max length: 50

**description** (string)  
An optional description for the ledger distribute operation.

```javascript
const request: TransferLedgerDistributeRequest = {
   from_client_id: '6a65dh3d1h0d1027121ak184',
   to_client_id: '415ab64b87ec47401d000002'
   amount: '12.34',
   idempotency_key: 'test_distribute_abc',
   description: 'distribute',
};
try {
  const response = await client.transferLedgerDistribute(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/ledger/get 

#### Retrieve Plaid Ledger balance 

Use the [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) endpoint to view a balance on the ledger held with Plaid.

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

**ledger\_id** (string)  
Specify which ledger balance to get. Customers can find a list of ledger\_ids in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance.

**originator\_client\_id** (string)  
Client ID of the end customer.

```javascript
try {
  const response = await client.transferLedgerGet({}});
  const available_balance = response.data.balance.available;
  const pending_balance = response.data.balance.pending;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**ledger\_id** (string)  
The unique identifier of the Ledger that was returned.

**balance** (object)  
Information about the balance of the ledger held with Plaid.

**balance->available** (string)  
The amount of this balance available for use (decimal string with two digits of precision e.g. "10.00").

**balance->pending** (string)  
The amount of pending funds that are in processing (decimal string with two digits of precision e.g. "10.00").

**name** (string)  
The name of the Ledger

**is\_default** (boolean)  
Whether this Ledger is the client's default ledger.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
  "name": "Default",
  "is_default": true,
  "balance": {
    "available": "1721.70",
    "pending": "123.45"
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/ledger/withdraw 

#### Withdraw funds from a Plaid Ledger balance 

Use the [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) endpoint to withdraw funds from a Plaid Ledger balance.

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

**originator\_client\_id** (string)  
Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to payout or collect funds. Only applicable for Platform customers. Do not include if you’re paying out to yourself.

**funding\_account\_id** (string)  
Specify which funding account to use. Customers can find a list of funding\_account\_ids in the Accounts page of the Plaid Dashboard, under the "Account ID" column. If this field is left blank, the funding account associated with the specified Ledger will be used. If an originator\_client\_id is specified, the funding\_account\_id must belong to the specified originator.

**ledger\_id** (string)  
Specify which ledger balance to withdraw from. Customers can find a list of ledger\_ids in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance.

**amount** (required, string)  
A positive amount of how much will be withdrawn from the ledger balance (decimal string with two digits of precision e.g. "5.50").

**description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. Max length: 10

**idempotency\_key** (required, string)  
A unique key provided by the client, per unique ledger withdraw. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger withdraw fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single withdraw is created. Max length: 50

**network** (required, string)  
The network or rails used for the transfer. For transfers submitted as ach or same-day-ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID\_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create. Wire transfers are currently in early availability. To request access to wire as a payment network, contact your Account Manager. For transfers submitted as wire, the type must be credit; wire debits are not supported. The cutoff to submit a wire payment is 4:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: ach, same-day-ach, rtp, wire

```javascript
const request: TransferLedgerWithdrawRequest = {
  amount: '12.34',
  network: 'ach',
  idempotency_key: 'test_deposit_abc',
  description: 'withdraw',
};
try {
  const response = await client.transferLedgerWithdraw(request);
  const sweep = response.data.sweep;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**sweep** (object)  
Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type swept or return\_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep\_id. swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return\_swept events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the swept and return\_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.

**sweep->id** (string)  
Identifier of the sweep.

**sweep->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**sweep->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**sweep->created** (string)  
The datetime when the sweep occurred, in RFC 3339 format. Format: date-time

**sweep->amount** (string)  
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

**sweep->iso\_currency\_code** (string)  
The currency of the sweep, e.g. "USD".

**sweep->settled** (nullable, string)  
The date when the sweep settled, in the YYYY-MM-DD format. Format: date

**sweep->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: date

**sweep->status** (nullable, string)  
The status of a sweep transfer "pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled. This is the terminal state of a successful credit sweep. "returned" - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. "funds\_available" - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. "failed" - The sweep has failed. This is the terminal state of a failed sweep. Possible values: pending, posted, settled, funds\_available, returned, failed, null

**sweep->trigger** (nullable, string)  
The trigger of the sweep "manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance\_threshold" - The sweep is created by balance threshold setting "automatic\_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: manual, incoming, balance\_threshold, automatic\_aggregate

**sweep->description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

**sweep->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**sweep->failure\_reason** (nullable, object)  
The failure reason if the status for a sweep is "failed" or "returned". Null value otherwise.

**sweep->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the sweep status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**sweep->failure\_reason->description** (nullable, string)  
A human-readable description of the reason for the failure or reversal.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "sweep": {
    "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
    "created": "2020-08-06T17:27:15Z",
    "amount": "12.34",
    "iso_currency_code": "USD",
    "settled": null,
    "status": "pending",
    "trigger": "manual",
    "description": "withdraw",
    "network_trace_id": null
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/ledger/event/list 

#### List transfer ledger events 

Use the [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) endpoint to get a list of ledger events for a specific ledger based on specified filter criteria.

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

**originator\_client\_id** (string)  
Filter transfer events to only those with the specified originator client. (This field is specifically for resellers. Caller's client ID will be used if this field is not specified.)

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

**start\_date** (string)  
The start created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**end\_date** (string)  
The end created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**ledger\_id** (string)  
Plaid's unique identifier for a Plaid Ledger Balance.

**ledger\_event\_id** (string)  
Plaid's unique identifier for the ledger event.

**source\_type** (string)  
Source of the ledger event. "TRANSFER" - The source of the ledger event is a transfer "SWEEP" - The source of the ledger event is a sweep "REFUND" - The source of the ledger event is a refund Possible values: TRANSFER, SWEEP, REFUND

**source\_id** (string)  
Plaid's unique identifier for a transfer, sweep, or refund.

**count** (integer)  
The maximum number of transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned. Default: 25 Maximum: 25 Minimum: 1

**offset** (integer)  
The offset into the list of transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 events will be returned. Default: 0 Minimum: 0

```javascript
const request: TransferLedgerEventListRequest = {
    originator_client_id: "8945fedc-e703-463d-86b1-dc0607b55460",
    start_date: '2019-12-06T22:35:49Z',
    end_date: '2019-12-12T22:35:49Z',
    count: 14,
    offset: 2,
    ledger_id: "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
    ledger_event_id: "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    source_type: "transfer",
    source_id: "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
 };
try {
  const response = await plaidClient.transferLedgerEventList(request);
  const events = response.data.ledger_events;
  for (const event of events) {
    // iterate through events
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**ledger\_events** (\[object\])  
Plaid's unique identifier for this ledger event.

**ledger\_events->ledger\_id** (string)  
The ID of the ledger this event belongs to.

**ledger\_events->amount** (string)  
The amount of the ledger event as a decimal string.

**ledger\_events->transfer\_id** (nullable, string)  
The ID of the transfer source that triggered this ledger event.

**ledger\_events->refund\_id** (nullable, string)  
The ID of the refund source that triggered this ledger event.

**ledger\_events->sweep\_id** (nullable, string)  
The ID of the sweep source that triggered this ledger event.

**ledger\_events->description** (string)  
A description of the ledger event.

**ledger\_events->pending\_balance** (string)  
The new pending balance after this event.

**ledger\_events->available\_balance** (string)  
The new available balance after this event.

**ledger\_events->type** (string)  
The type of balance that was impacted by this event.

**ledger\_events->timestamp** (string)  
The datetime when this ledger event occurred. Format: date-time

**has\_more** (boolean)  
Whether there are more events to be pulled from the endpoint that have not already been returned

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "ledger_events": [
    {
      "ledger_event_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
      "amount": "100.00",
      "type": "deposit",
      "transfer_id": "460cbe92-2dcc-8eae",
      "description": "Converted to available",
      "pending_balance": "100.00",
      "available_balance": "100.00",
      "timestamp": "2023-12-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "request_id": "mdqfuVxeoza6mhu"
}
```

---


# API - Program Metrics | Plaid Docs

Program Metrics 
================

#### API reference for Transfer program metrics 

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

| Program Metrics |  |
| --- | --- |
| [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) | Get transfer product usage metrics |
| [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) | Get transfer product configuration |

\=\*=\*=\*=

#### /transfer/metrics/get 

#### Get transfer product usage metrics 

Use the [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) endpoint to view your transfer product usage metrics.

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

**originator\_client\_id** (string)  
The Plaid client ID of the transfer originator. Should only be present if client\_id is a Platform customer.

```javascript
const request: TransferMetricsGetRequest = {
  originator_client_id: '61b8f48ded273e001aa8db6d',
};


try {
  const response = await client.transferMetricsGet(request);
} catch (error) {
  // handle error
}
```

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

**daily\_debit\_transfer\_volume** (string)  
Sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

**daily\_credit\_transfer\_volume** (string)  
Sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

**monthly\_debit\_transfer\_volume** (string)  
Sum of dollar amount of debit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").

**monthly\_credit\_transfer\_volume** (string)  
Sum of dollar amount of credit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").

**iso\_currency\_code** (string)  
The currency of the dollar amount, e.g. "USD".

**return\_rates** (nullable, object)  
Details regarding return rates.

**return\_rates->last\_60d** (nullable, object)  
Details regarding return rates.

**return\_rates->last\_60d->overall\_return\_rate** (string)  
The overall return rate.

**return\_rates->last\_60d->unauthorized\_return\_rate** (string)  
The unauthorized return rate.

**return\_rates->last\_60d->administrative\_return\_rate** (string)  
The administrative return rate.

**authorization\_usage** (nullable, object)  
Details regarding authorization usage.

**authorization\_usage->daily\_credit\_utilization** (string)  
The daily credit utilization formatted as a decimal.

**authorization\_usage->daily\_debit\_utilization** (string)  
The daily debit utilization formatted as a decimal.

**authorization\_usage->monthly\_credit\_utilization** (string)  
The monthly credit utilization formatted as a decimal.

**authorization\_usage->monthly\_debit\_utilization** (string)  
The monthly debit utilization formatted as a decimal.

```json
{
  "daily_debit_transfer_volume": "1234.56",
  "daily_credit_transfer_volume": "567.89",
  "monthly_transfer_volume": "",
  "monthly_debit_transfer_volume": "10000.00",
  "monthly_credit_transfer_volume": "2345.67",
  "iso_currency_code": "USD",
  "request_id": "saKrIBuEB9qJZno",
  "return_rates": {
    "last_60d": {
      "overall_return_rate": "0.1023",
      "administrative_return_rate": "0.0160",
      "unauthorized_return_rate": "0.0028"
    }
  },
  "authorization_usage": {
    "daily_credit_utilization": "0.2300",
    "daily_debit_utilization": "0.3401",
    "monthly_credit_utilization": "0.9843",
    "monthly_debit_utilization": "0.3220"
  }
}
```

\=\*=\*=\*=

#### /transfer/configuration/get 

#### Get transfer product configuration 

Use the [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) endpoint to view your transfer product configurations.

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

**originator\_client\_id** (string)  
The Plaid client ID of the transfer originator. Should only be present if client\_id is a Platform customer.

```javascript
const request: TransferConfigurationGetRequest = {
  originator_client_id: '61b8f48ded273e001aa8db6d',
};


try {
  const response = await client.transferConfigurationGet(request);
} catch (error) {
  // handle error
}
```

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

**max\_single\_transfer\_credit\_amount** (string)  
The max limit of dollar amount of a single credit transfer (decimal string with two digits of precision e.g. "10.00").

**max\_single\_transfer\_debit\_amount** (string)  
The max limit of dollar amount of a single debit transfer (decimal string with two digits of precision e.g. "10.00").

**max\_daily\_credit\_amount** (string)  
The max limit of sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

**max\_daily\_debit\_amount** (string)  
The max limit of sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

**max\_monthly\_credit\_amount** (string)  
The max limit of sum of dollar amount of credit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").

**max\_monthly\_debit\_amount** (string)  
The max limit of sum of dollar amount of debit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").

**iso\_currency\_code** (string)  
The currency of the dollar amount, e.g. "USD".

```json
{
  "max_single_transfer_amount": "",
  "max_single_transfer_credit_amount": "1000.00",
  "max_single_transfer_debit_amount": "1000.00",
  "max_daily_credit_amount": "50000.00",
  "max_daily_debit_amount": "50000.00",
  "max_monthly_amount": "",
  "max_monthly_credit_amount": "500000.00",
  "max_monthly_debit_amount": "500000.00",
  "iso_currency_code": "USD",
  "request_id": "saKrIBuEB9qJZno"
}
```

---


# API - Platform Payments | Plaid Docs

Transfer Platform Payments 
===========================

#### API reference for Transfer Platform Payments endpoints 

For how-to guidance, see the [Platform Payments documentation](https://plaid.com/docs/transfer/platform-payments/index.html.md) .

| Platform Payments |  |
| --- | --- |
| [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) | Create a new originator |
| [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) | Get the status of an originator's onboarding |
| [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) | Get the status of all originators' onboarding |
| [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) | Create a new funding account for an originator |
| [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) | Generate a Plaid-hosted onboarding UI URL |

\=\*=\*=\*=

#### /transfer/originator/create 

#### Create a new originator 

Use the [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) endpoint to create a new originator and return an `originator_client_id`.

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

**company\_name** (required, string)  
The company name of the end customer being created. This will be displayed in public-facing surfaces, e.g. Plaid Dashboard. Min length: 1

```javascript
const request: TransferOriginatorCreateRequest = {
  company_name: 'Marketplace of Shannon',
};


try {
  const response = await client.transferOriginatorCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**originator\_client\_id** (string)  
Client ID of the originator. This identifier will be used when creating transfers and should be stored associated with end user information.

**company\_name** (string)  
The company name of the end customer.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "originator_client_id": "6a65dh3d1h0d1027121ak184",
  "company_name": "Marketplace of Shannon",
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /transfer/originator/get 

#### Get status of an originator's onboarding 

The [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) endpoint gets status updates for an originator's onboarding process. This information is also available via the Transfer page on the Plaid dashboard.

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

**originator\_client\_id** (required, string)  
Client ID of the end customer (i.e. the originator).

```javascript
const request: TransferOriginatorGetRequest = {
  originator_client_id: '6a65dh3d1h0d1027121ak184',
};


try {
  const response = await client.transferOriginatorGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**originator** (object)  
Originator and their status.

**originator->client\_id** (string)  
Originator’s client ID.

**originator->transfer\_diligence\_status** (string)  
Originator’s diligence status. Possible values: not\_submitted, submitted, under\_review, approved, denied, more\_information\_required

**originator->company\_name** (string)  
The company name of the end customer.

**originator->outstanding\_requirements** (\[object\])  
List of outstanding requirements for scaled platform originators. Only populated when transfer\_diligence\_status is more\_information\_required.

**originator->outstanding\_requirements->requirement\_type** (string)  
The type of requirement.

**originator->outstanding\_requirements->person\_id** (nullable, string)  
UUID of the person associated with the requirement. Only present for individual-scoped requirements.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "originator": {
    "client_id": "6a65dh3d1h0d1027121ak184",
    "transfer_diligence_status": "approved",
    "company_name": "Plaid"
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/originator/list 

#### Get status of all originators' onboarding 

The [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) endpoint gets status updates for all of your originators' onboarding. This information is also available via the Plaid dashboard.

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

**count** (integer)  
The maximum number of originators to return. Maximum: 25 Minimum: 1 Default: 25

**offset** (integer)  
The number of originators to skip before returning results. Minimum: 0 Default: 0

```javascript
const request: TransferOriginatorListRequest = {
  count: 14,
  offset: 2,
};


try {
  const response = await client.transferOriginatorList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**originators** (\[object\])  
Originator’s client ID.

**originators->transfer\_diligence\_status** (string)  
Originator’s diligence status. Possible values: not\_submitted, submitted, under\_review, approved, denied, more\_information\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "originators": [
    {
      "client_id": "6a65dh3d1h0d1027121ak184",
      "transfer_diligence_status": "approved"
    },
    {
      "client_id": "8g89as4d2k1d9852938ba019",
      "transfer_diligence_status": "denied"
    }
  ],
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /transfer/originator/funding\_account/create 

#### Create a new funding account for an originator 

Use the [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) endpoint to create a new funding account for the originator.

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

**originator\_client\_id** (required, string)  
The Plaid client ID of the transfer originator.

**funding\_account** (required, object)  
The originator's funding account, linked with Plaid Link or /transfer/migrate\_account.

**funding\_account->access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**funding\_account->account\_id** (required, string)  
The Plaid account\_id for the newly created Item.

**funding\_account->display\_name** (string)  
The name for the funding account that is displayed in the Plaid dashboard.

```javascript
const request: TransferOriginatorFundingAccountCreateRequest = {
  originator_client_id: '6a65dh3d1h0d1027121ak184',
  funding_account: {
    access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
    account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
    display_name: "New Funding Account",
  },
};


try {
  const response = await client.transferOriginatorFundingAccountCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/questionnaire/create 

#### Generate a Plaid-hosted onboarding UI URL. 

The [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) endpoint generates a Plaid-hosted onboarding UI URL. Redirect the originator to this URL to provide their due diligence information and agree to Plaid’s terms for ACH money movement.

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

**originator\_client\_id** (required, string)  
Client ID of the end customer.

**redirect\_uri** (required, string)  
URL the end customer will be redirected to after completing questions in Plaid-hosted onboarding flow.

```javascript
const request: TransferQuestionnaireCreateRequest = {
  originator_client_id: '6a65dh3d1h0d1027121ak184',
  redirect_uri: 'https://example.com',
};


try {
  const response = await client.transferQuestionnaireCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**onboarding\_url** (string)  
Plaid-hosted onboarding URL that you will redirect the end customer to.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "onboarding_url": "https://plaid.com/originator/hIFGXx1zM5pFerygu7lw",
  "request_id": "saKrIBuEB9qJZno"
}
```

---


# API - Reading Transfers | Plaid Docs

Reading Transfers and Transfer events 
======================================

#### API reference for Transfer read and Transfer event endpoints and webhooks 

For how-to guidance, see the [Transfer events documentation](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) .

| Reading Transfers |  |
| --- | --- |
| [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) | Retrieve information about a transfer |
| [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) | Retrieve a list of transfers and their statuses |
| [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) | Retrieve a list of transfer events |
| [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) | Sync transfer events |
| [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) | Retrieve information about a sweep |
| [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) | Retrieve a list of sweeps |

| Webhooks |  |
| --- | --- |
| [TRANSFER\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer_events_update) | New transfer events available |

### Endpoints 

\=\*=\*=\*=

#### /transfer/get 

#### Retrieve a transfer 

The [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) endpoint fetches information about the transfer corresponding to the given `transfer_id` or `authorization_id`. One of `transfer_id` or `authorization_id` must be populated but not both.

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

**transfer\_id** (string)  
Plaid’s unique identifier for a transfer.

**authorization\_id** (string)  
Plaid’s unique identifier for a transfer authorization.

```javascript
const request: TransferGetRequest = {
  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};
try {
  const response = await plaidClient.transferGet(request);
  const transfer = response.data.transfer;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transfer** (object)  
Represents a transfer within the Transfers API.

**transfer->id** (string)  
Plaid’s unique identifier for a transfer.

**transfer->authorization\_id** (string)  
Plaid’s unique identifier for a transfer authorization.

**transfer->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**transfer->account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**transfer->funding\_account\_id** (nullable, string)  
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

**transfer->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfer->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**transfer->user** (object)  
The legal name and other information for the account holder.

**transfer->user->legal\_name** (string)  
The user's legal name.

**transfer->user->phone\_number** (nullable, string)  
The user's phone number.

**transfer->user->email\_address** (nullable, string)  
The user's email address.

**transfer->user->address** (nullable, object)  
The address associated with the account holder.

**transfer->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**transfer->user->address->city** (nullable, string)  
Ex. "San Francisco"

**transfer->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**transfer->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**transfer->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**transfer->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**transfer->description** (string)  
The description of the transfer.

**transfer->created** (string)  
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**transfer->status** (string)  
The status of the transfer. pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: The transfer was successfully completed by the payment network. Note that funds from received debits are not available to be moved out of the Ledger until the transfer reaches funds\_available status. For credit transactions, settled means the funds have been delivered to the receiving bank account. This is the terminal state of a successful credit transfer. funds\_available: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) This is the terminal state of a successful debit transfer. cancelled: The transfer was cancelled by the client. This is the terminal state of a cancelled transfer. failed: The transfer failed, no funds were moved. This is the terminal state of a failed transfer. returned: A posted transfer was returned. This is the terminal state of a returned transfer. Possible values: pending, posted, settled, funds\_available, cancelled, failed, returned

**transfer->sweep\_status** (nullable, string)  
The status of the sweep for the transfer. unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept\_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return\_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept) Possible values: null, unswept, swept, swept\_settled, return\_swept

**transfer->network** (string)  
The network or rails used for the transfer. For transfers submitted as ach or same-day-ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID\_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create. Wire transfers are currently in early availability. To request access to wire as a payment network, contact your Account Manager. For transfers submitted as wire, the type must be credit; wire debits are not supported. The cutoff to submit a wire payment is 4:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: ach, same-day-ach, rtp, wire

**transfer->wire\_details** (nullable, object)  
Information specific to wire transfers.

**transfer->wire\_details->message\_to\_beneficiary** (nullable, string)  
Additional information from the wire originator to the beneficiary. Max 140 characters.

**transfer->wire\_details->wire\_return\_fee** (nullable, string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**transfer->cancellable** (boolean)  
When true, you can still cancel this transfer.

**transfer->failure\_reason** (nullable, object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**transfer->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfer->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**transfer->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfer->metadata** (nullable, object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**transfer->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**transfer->standard\_return\_window** (nullable, string)  
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD. Format: date

**transfer->unauthorized\_return\_window** (nullable, string)  
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD. Format: date

**transfer->expected\_settlement\_date** (nullable, string)  
The date when settlement will occur between Plaid and the receiving bank (RDFI). For ACH debits, this is the date funds will be pulled from the bank account being debited. For ACH credits, this is the date funds will be delivered to the bank account being credited. Only set for ACH transfers; null for non-ACH transfers. This will be of the form YYYY-MM-DD. Format: date

**transfer->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a transfer will be made available and can be withdrawn from the associated ledger balance, assuming the debit does not return before this date. If the transfer does return before this date, this field will be null. Only applies to debit transfers. This will be of the form YYYY-MM-DD. Format: date

**transfer->originator\_client\_id** (nullable, string)  
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a Platform customer.

**transfer->refunds** (\[object\])  
A list of refunds associated with this transfer.

**transfer->refunds->id** (string)  
Plaid’s unique identifier for a refund.

**transfer->refunds->transfer\_id** (string)  
The ID of the transfer to refund.

**transfer->refunds->amount** (string)  
The amount of the refund (decimal string with two digits of precision e.g. "10.00").

**transfer->refunds->status** (string)  
The status of the refund. pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned. Possible values: pending, posted, cancelled, failed, settled, returned

**transfer->refunds->failure\_reason** (nullable, object)  
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

**transfer->refunds->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the refund status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfer->refunds->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors. This field is deprecated in favor of the more versatile failure\_code, which encompasses non-ACH failure codes as well.

**transfer->refunds->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfer->refunds->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfer->refunds->created** (string)  
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**transfer->refunds->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**transfer->recurring\_transfer\_id** (nullable, string)  
The id of the recurring transfer if this transfer belongs to a recurring transfer.

**transfer->expected\_sweep\_settlement\_schedule** (\[object\])  
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.

**transfer->expected\_sweep\_settlement\_schedule->sweep\_settlement\_date** (string)  
The settlement date of a sweep for this transfer. Format: date

**transfer->expected\_sweep\_settlement\_schedule->swept\_settled\_amount** (string)  
The accumulated amount that has been swept by sweep\_settlement\_date.

**transfer->credit\_funds\_source** (deprecated, nullable, string)  
This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers. sweep - Sweep funds from your funding account prefunded\_rtp\_credits - Use your prefunded RTP credit balance with Plaid prefunded\_ach\_credits - Use your prefunded ACH credit balance with Plaid Possible values: sweep, prefunded\_rtp\_credits, prefunded\_ach\_credits, null

**transfer->facilitator\_fee** (string)  
The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the transfer.amount.

**transfer->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfer": {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
    "ach_class": "ppd",
    "amount": "12.34",
    "cancellable": true,
    "created": "2020-08-06T17:27:15Z",
    "description": "Desc",
    "guarantee_decision": null,
    "guarantee_decision_rationale": null,
    "failure_reason": {
      "failure_code": "R13",
      "description": "Invalid ACH routing number"
    },
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "network": "ach",
    "origination_account_id": "",
    "originator_client_id": null,
    "refunds": [],
    "status": "pending",
    "type": "credit",
    "iso_currency_code": "USD",
    "standard_return_window": "2020-08-07",
    "unauthorized_return_window": "2020-10-07",
    "expected_settlement_date": "2020-08-04",
    "user": {
      "email_address": "acharleston@email.com",
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128",
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94053",
        "country": "US"
      }
    },
    "recurring_transfer_id": null,
    "credit_funds_source": "sweep",
    "facilitator_fee": "1.23",
    "network_trace_id": null
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/list 

#### List transfers 

Use the [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) endpoint to see a list of all your transfers and their statuses. Results are paginated; use the `count` and `offset` query parameters to retrieve the desired transfers.

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

**start\_date** (string)  
The start created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**end\_date** (string)  
The end created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**count** (integer)  
The maximum number of transfers to return. Minimum: 1 Maximum: 25 Default: 25

**offset** (integer)  
The number of transfers to skip before returning results. Default: 0 Minimum: 0

**originator\_client\_id** (string)  
Filter transfers to only those with the specified originator client.

**funding\_account\_id** (string)  
Filter transfers to only those with the specified funding\_account\_id.

```javascript
const request: TransferListRequest = {
  start_date: '2019-12-06T22:35:49Z',
  end_date: '2019-12-12T22:35:49Z',
  count: 14,
  offset: 2,
  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
};
try {
  const response = await plaidClient.transferList(request);
  const transfers = response.data.transfers;
  for (const transfer of transfers) {
    // iterate through transfers
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**transfers** (\[object\])  
Plaid’s unique identifier for a transfer.

**transfers->authorization\_id** (string)  
Plaid’s unique identifier for a transfer authorization.

**transfers->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**transfers->account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**transfers->funding\_account\_id** (nullable, string)  
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

**transfers->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfers->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**transfers->user** (object)  
The legal name and other information for the account holder.

**transfers->user->legal\_name** (string)  
The user's legal name.

**transfers->user->phone\_number** (nullable, string)  
The user's phone number.

**transfers->user->email\_address** (nullable, string)  
The user's email address.

**transfers->user->address** (nullable, object)  
The address associated with the account holder.

**transfers->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**transfers->user->address->city** (nullable, string)  
Ex. "San Francisco"

**transfers->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**transfers->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**transfers->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**transfers->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**transfers->description** (string)  
The description of the transfer.

**transfers->created** (string)  
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**transfers->status** (string)  
The status of the transfer. pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: The transfer was successfully completed by the payment network. Note that funds from received debits are not available to be moved out of the Ledger until the transfer reaches funds\_available status. For credit transactions, settled means the funds have been delivered to the receiving bank account. This is the terminal state of a successful credit transfer. funds\_available: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) This is the terminal state of a successful debit transfer. cancelled: The transfer was cancelled by the client. This is the terminal state of a cancelled transfer. failed: The transfer failed, no funds were moved. This is the terminal state of a failed transfer. returned: A posted transfer was returned. This is the terminal state of a returned transfer. Possible values: pending, posted, settled, funds\_available, cancelled, failed, returned

**transfers->sweep\_status** (nullable, string)  
The status of the sweep for the transfer. unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept\_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return\_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept) Possible values: null, unswept, swept, swept\_settled, return\_swept

**transfers->network** (string)  
The network or rails used for the transfer. For transfers submitted as ach or same-day-ach, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as same-day-ach, the Same Day ACH cutoff is 3:30 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID\_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create. Wire transfers are currently in early availability. To request access to wire as a payment network, contact your Account Manager. For transfers submitted as wire, the type must be credit; wire debits are not supported. The cutoff to submit a wire payment is 4:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: ach, same-day-ach, rtp, wire

**transfers->wire\_details** (nullable, object)  
Information specific to wire transfers.

**transfers->wire\_details->message\_to\_beneficiary** (nullable, string)  
Additional information from the wire originator to the beneficiary. Max 140 characters.

**transfers->wire\_details->wire\_return\_fee** (nullable, string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**transfers->cancellable** (boolean)  
When true, you can still cancel this transfer.

**transfers->failure\_reason** (nullable, object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**transfers->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfers->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**transfers->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfers->metadata** (nullable, object)  
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters

**transfers->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**transfers->standard\_return\_window** (nullable, string)  
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD. Format: date

**transfers->unauthorized\_return\_window** (nullable, string)  
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD. Format: date

**transfers->expected\_settlement\_date** (nullable, string)  
The date when settlement will occur between Plaid and the receiving bank (RDFI). For ACH debits, this is the date funds will be pulled from the bank account being debited. For ACH credits, this is the date funds will be delivered to the bank account being credited. Only set for ACH transfers; null for non-ACH transfers. This will be of the form YYYY-MM-DD. Format: date

**transfers->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a transfer will be made available and can be withdrawn from the associated ledger balance, assuming the debit does not return before this date. If the transfer does return before this date, this field will be null. Only applies to debit transfers. This will be of the form YYYY-MM-DD. Format: date

**transfers->originator\_client\_id** (nullable, string)  
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a Platform customer.

**transfers->refunds** (\[object\])  
A list of refunds associated with this transfer.

**transfers->refunds->id** (string)  
Plaid’s unique identifier for a refund.

**transfers->refunds->transfer\_id** (string)  
The ID of the transfer to refund.

**transfers->refunds->amount** (string)  
The amount of the refund (decimal string with two digits of precision e.g. "10.00").

**transfers->refunds->status** (string)  
The status of the refund. pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned. Possible values: pending, posted, cancelled, failed, settled, returned

**transfers->refunds->failure\_reason** (nullable, object)  
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

**transfers->refunds->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the refund status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfers->refunds->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors. This field is deprecated in favor of the more versatile failure\_code, which encompasses non-ACH failure codes as well.

**transfers->refunds->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfers->refunds->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfers->refunds->created** (string)  
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**transfers->refunds->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**transfers->recurring\_transfer\_id** (nullable, string)  
The id of the recurring transfer if this transfer belongs to a recurring transfer.

**transfers->expected\_sweep\_settlement\_schedule** (\[object\])  
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.

**transfers->expected\_sweep\_settlement\_schedule->sweep\_settlement\_date** (string)  
The settlement date of a sweep for this transfer. Format: date

**transfers->expected\_sweep\_settlement\_schedule->swept\_settled\_amount** (string)  
The accumulated amount that has been swept by sweep\_settlement\_date.

**transfers->credit\_funds\_source** (deprecated, nullable, string)  
This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers. sweep - Sweep funds from your funding account prefunded\_rtp\_credits - Use your prefunded RTP credit balance with Plaid prefunded\_ach\_credits - Use your prefunded ACH credit balance with Plaid Possible values: sweep, prefunded\_rtp\_credits, prefunded\_ach\_credits, null

**transfers->facilitator\_fee** (string)  
The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the transfer.amount.

**transfers->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfers": [
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
      "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
      "ach_class": "ppd",
      "amount": "12.34",
      "cancellable": true,
      "created": "2019-12-09T17:27:15Z",
      "description": "Desc",
      "guarantee_decision": null,
      "guarantee_decision_rationale": null,
      "failure_reason": {
        "failure_code": "R13",
        "description": "Invalid ACH routing number"
      },
      "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "network": "ach",
      "origination_account_id": "",
      "originator_client_id": null,
      "refunds": [],
      "status": "pending",
      "type": "credit",
      "iso_currency_code": "USD",
      "standard_return_window": "2020-08-07",
      "unauthorized_return_window": "2020-10-07",
      "expected_settlement_date": "2020-08-04",
      "user": {
        "email_address": "acharleston@email.com",
        "legal_name": "Anne Charleston",
        "phone_number": "510-555-0128",
        "address": {
          "street": "123 Main St.",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94053",
          "country": "US"
        }
      },
      "recurring_transfer_id": null,
      "credit_funds_source": "sweep",
      "facilitator_fee": "1.23",
      "network_trace_id": null
    }
  ],
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/event/list 

#### List transfer events 

Use the [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) endpoint to get a list of transfer events based on specified filter criteria.

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

**start\_date** (string)  
The start created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**end\_date** (string)  
The end created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**transfer\_id** (string)  
Plaid’s unique identifier for a transfer.

**account\_id** (string)  
The account ID to get events for all transactions to/from an account.

**transfer\_type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into your origination account; a credit indicates a transfer of money out of your origination account. Possible values: debit, credit, null

**event\_types** (\[string\])  
Filter events by event type. Possible values: pending, cancelled, failed, posted, settled, funds\_available, returned, swept, swept\_settled, return\_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed, sweep.funds\_available, refund.pending, refund.cancelled, refund.failed, refund.posted, refund.settled, refund.returned, refund.swept, refund.return\_swept

**sweep\_id** (string)  
Plaid’s unique identifier for a sweep.

**count** (integer)  
The maximum number of transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned. Default: 25 Maximum: 25 Minimum: 1

**offset** (integer)  
The offset into the list of transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 events will be returned. Default: 0 Minimum: 0

**originator\_client\_id** (string)  
Filter transfer events to only those with the specified originator client.

**funding\_account\_id** (string)  
Filter transfer events to only those with the specified funding\_account\_id.

```javascript
const request: TransferEventListRequest = {
  start_date: '2019-12-06T22:35:49Z',
  end_date: '2019-12-12T22:35:49Z',
  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  transfer_type: 'credit',
  event_types: ['pending', 'posted'],
  count: 14,
  offset: 2,
  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
};
try {
  const response = await plaidClient.transferEventList(request);
  const events = response.data.transfer_events;
  for (const event of events) {
    // iterate through events
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

integer

**transfer\_events** (\[object\])  
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: 0

**transfer\_events->timestamp** (string)  
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**transfer\_events->event\_type** (string)  
The type of event that this transfer represents. Event types with prefix sweep represents events for Plaid Ledger sweeps. pending: A new transfer was created; it is in the pending state. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. posted: The transfer has been successfully submitted to the payment network. settled: The transfer has been successfully completed by the payment network. funds\_available: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) returned: A posted transfer was returned. swept: The transfer was swept to / from the sweep account. swept\_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return\_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account. sweep.pending: A new ledger sweep was created; it is in the pending state. sweep.posted: The ledger sweep has been successfully submitted to the payment network. sweep.settled: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun. sweep.returned: A posted ledger sweep was returned. sweep.failed: The ledger sweep failed, no funds were moved. sweep.funds\_available: Funds from the ledger sweep have been released from hold and applied to the ledger's available balance. This is only applicable to debits. refund.pending: A new refund was created; it is in the pending state. refund.cancelled: The refund was cancelled. refund.failed: The refund failed, no funds were moved. refund.posted: The refund has been successfully submitted to the payment network. refund.settled: The refund transaction has settled in the Plaid linked account. refund.returned: A posted refund was returned. refund.swept: The refund was swept from the sweep account. refund.return\_swept: Due to the refund being returned, funds were pushed back to the sweep account. Possible values: pending, cancelled, failed, posted, settled, funds\_available, returned, swept, swept\_settled, return\_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed, sweep.funds\_available, refund.pending, refund.cancelled, refund.failed, refund.posted, refund.settled, refund.returned, refund.swept, refund.return\_swept

**transfer\_events->account\_id** (string)  
The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.

**transfer\_events->funding\_account\_id** (nullable, string)  
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

**transfer\_events->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfer\_events->transfer\_id** (string)  
Plaid's unique identifier for a transfer. This field is an empty string for Plaid Ledger Sweep events.

**transfer\_events->transfer\_type** (string)  
The type of transfer. Valid values are debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. This field is omitted for Plaid Ledger Sweep events. Possible values: debit, credit

**transfer\_events->transfer\_amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events.

**transfer\_events->failure\_reason** (nullable, object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**transfer\_events->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfer\_events->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**transfer\_events->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfer\_events->sweep\_id** (nullable, string)  
Plaid’s unique identifier for a sweep.

**transfer\_events->sweep\_amount** (nullable, string)  
A signed amount of how much was swept or return\_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").

**transfer\_events->refund\_id** (nullable, string)  
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.

**transfer\_events->originator\_client\_id** (nullable, string)  
The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).

**transfer\_events->intent\_id** (nullable, string)  
The id returned by the /transfer/intent/create endpoint, for transfers created via Transfer UI. For transfers not created by Transfer UI, the value is null. This will currently only be populated for RfP transfers.

**transfer\_events->wire\_return\_fee** (nullable, string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**has\_more** (boolean)  
Whether there are more events to be pulled from the endpoint that have not already been returned

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfer_events": [
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
      "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
      "transfer_amount": "12.34",
      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "transfer_type": "credit",
      "event_id": 1,
      "event_type": "posted",
      "failure_reason": null,
      "origination_account_id": "",
      "originator_client_id": "569ed2f36b3a3a021713abc1",
      "refund_id": null,
      "sweep_amount": null,
      "sweep_id": null,
      "timestamp": "2019-12-09T17:27:15Z"
    }
  ],
  "has_more": true,
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /transfer/event/sync 

#### Sync transfer events 

[/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) allows you to request up to the next 25 transfer events that happened after a specific `event_id`. Use the [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) endpoint to guarantee you have seen all transfer events.

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

**after\_id** (required, integer)  
The latest (largest) event\_id fetched via the sync endpoint, or 0 initially. Minimum: 0

**count** (integer)  
The maximum number of transfer events to return. Default: 25 Minimum: 1 Maximum: 25

```javascript
const request: TransferEventListRequest = {
  after_id: 4,
  count: 22,
};
try {
  const response = await plaidClient.transferEventSync(request);
  const events = response.data.transfer_events;
  for (const event of events) {
    // iterate through events
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

integer

**transfer\_events** (\[object\])  
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: 0

**transfer\_events->timestamp** (string)  
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**transfer\_events->event\_type** (string)  
The type of event that this transfer represents. Event types with prefix sweep represents events for Plaid Ledger sweeps. pending: A new transfer was created; it is in the pending state. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. posted: The transfer has been successfully submitted to the payment network. settled: The transfer has been successfully completed by the payment network. funds\_available: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) returned: A posted transfer was returned. swept: The transfer was swept to / from the sweep account. swept\_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return\_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account. sweep.pending: A new ledger sweep was created; it is in the pending state. sweep.posted: The ledger sweep has been successfully submitted to the payment network. sweep.settled: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun. sweep.returned: A posted ledger sweep was returned. sweep.failed: The ledger sweep failed, no funds were moved. sweep.funds\_available: Funds from the ledger sweep have been released from hold and applied to the ledger's available balance. This is only applicable to debits. refund.pending: A new refund was created; it is in the pending state. refund.cancelled: The refund was cancelled. refund.failed: The refund failed, no funds were moved. refund.posted: The refund has been successfully submitted to the payment network. refund.settled: The refund transaction has settled in the Plaid linked account. refund.returned: A posted refund was returned. refund.swept: The refund was swept from the sweep account. refund.return\_swept: Due to the refund being returned, funds were pushed back to the sweep account. Possible values: pending, cancelled, failed, posted, settled, funds\_available, returned, swept, swept\_settled, return\_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed, sweep.funds\_available, refund.pending, refund.cancelled, refund.failed, refund.posted, refund.settled, refund.returned, refund.swept, refund.return\_swept

**transfer\_events->account\_id** (string)  
The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.

**transfer\_events->funding\_account\_id** (nullable, string)  
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

**transfer\_events->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**transfer\_events->transfer\_id** (string)  
Plaid's unique identifier for a transfer. This field is an empty string for Plaid Ledger Sweep events.

**transfer\_events->transfer\_type** (string)  
The type of transfer. Valid values are debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. This field is omitted for Plaid Ledger Sweep events. Possible values: debit, credit

**transfer\_events->transfer\_amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events.

**transfer\_events->failure\_reason** (nullable, object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**transfer\_events->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**transfer\_events->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**transfer\_events->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**transfer\_events->sweep\_id** (nullable, string)  
Plaid’s unique identifier for a sweep.

**transfer\_events->sweep\_amount** (nullable, string)  
A signed amount of how much was swept or return\_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").

**transfer\_events->refund\_id** (nullable, string)  
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.

**transfer\_events->originator\_client\_id** (nullable, string)  
The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).

**transfer\_events->intent\_id** (nullable, string)  
The id returned by the /transfer/intent/create endpoint, for transfers created via Transfer UI. For transfers not created by Transfer UI, the value is null. This will currently only be populated for RfP transfers.

**transfer\_events->wire\_return\_fee** (nullable, string)  
The fee amount deducted from the original transfer during a wire return, if applicable.

**has\_more** (boolean)  
Whether there are more events to be pulled from the endpoint that have not already been returned

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transfer_events": [
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
      "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
      "transfer_amount": "12.34",
      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "transfer_type": "credit",
      "event_id": 1,
      "event_type": "pending",
      "failure_reason": null,
      "origination_account_id": "",
      "originator_client_id": null,
      "refund_id": null,
      "sweep_amount": null,
      "sweep_id": null,
      "timestamp": "2019-12-09T17:27:15Z"
    }
  ],
  "has_more": true,
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /transfer/sweep/get 

#### Retrieve a sweep 

The [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) endpoint fetches a sweep corresponding to the given `sweep_id`.

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

**sweep\_id** (required, string)  
Plaid's unique identifier for the sweep (UUID) or a shortened form consisting of the first 8 characters of the identifier (8-digit hexadecimal string).

```javascript
const request: TransferSweepGetRequest = {
  sweep_id: '8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee',
};
try {
  const response = await plaidClient.transferSweepGet(request);
  const sweep = response.data.sweep;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**sweep** (object)  
Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type swept or return\_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep\_id. swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return\_swept events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the swept and return\_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.

**sweep->id** (string)  
Identifier of the sweep.

**sweep->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**sweep->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**sweep->created** (string)  
The datetime when the sweep occurred, in RFC 3339 format. Format: date-time

**sweep->amount** (string)  
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

**sweep->iso\_currency\_code** (string)  
The currency of the sweep, e.g. "USD".

**sweep->settled** (nullable, string)  
The date when the sweep settled, in the YYYY-MM-DD format. Format: date

**sweep->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: date

**sweep->status** (nullable, string)  
The status of a sweep transfer "pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled. This is the terminal state of a successful credit sweep. "returned" - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. "funds\_available" - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. "failed" - The sweep has failed. This is the terminal state of a failed sweep. Possible values: pending, posted, settled, funds\_available, returned, failed, null

**sweep->trigger** (nullable, string)  
The trigger of the sweep "manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance\_threshold" - The sweep is created by balance threshold setting "automatic\_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: manual, incoming, balance\_threshold, automatic\_aggregate

**sweep->description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

**sweep->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**sweep->failure\_reason** (nullable, object)  
The failure reason if the status for a sweep is "failed" or "returned". Null value otherwise.

**sweep->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the sweep status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**sweep->failure\_reason->description** (nullable, string)  
A human-readable description of the reason for the failure or reversal.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "sweep": {
    "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
    "created": "2020-08-06T17:27:15Z",
    "amount": "12.34",
    "iso_currency_code": "USD",
    "settled": "2020-08-07",
    "status": "settled",
    "network_trace_id": "123456789012345"
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/sweep/list 

#### List sweeps 

The [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) endpoint fetches sweeps matching the given filters.

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

**start\_date** (string)  
The start created datetime of sweeps to return (RFC 3339 format). Format: date-time

**end\_date** (string)  
The end created datetime of sweeps to return (RFC 3339 format). Format: date-time

**count** (integer)  
The maximum number of sweeps to return. Minimum: 1 Maximum: 25 Default: 25

**offset** (integer)  
The number of sweeps to skip before returning results. Default: 0 Minimum: 0

**amount** (string)  
Filter sweeps to only those with the specified amount.

**status** (string)  
The status of a sweep transfer "pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled. This is the terminal state of a successful credit sweep. "returned" - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. "funds\_available" - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. "failed" - The sweep has failed. This is the terminal state of a failed sweep. Possible values: pending, posted, settled, funds\_available, returned, failed, null

**originator\_client\_id** (string)  
Filter sweeps to only those with the specified originator client.

**funding\_account\_id** (string)  
Filter sweeps to only those with the specified funding\_account\_id.

**transfer\_id** (string)  
Filter sweeps to only those with the included transfer\_id.

**trigger** (string)  
The trigger of the sweep "manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance\_threshold" - The sweep is created by balance threshold setting "automatic\_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: manual, incoming, balance\_threshold, automatic\_aggregate

```javascript
const request: TransferSweepListRequest = {
  start_date: '2019-12-06T22:35:49Z',
  end_date: '2019-12-12T22:35:49Z',
  count: 14,
  offset: 2,
};
try {
  const response = await plaidClient.transferSweepList(request);
  const sweeps = response.data.sweeps;
  for (const sweep of sweeps) {
    // iterate through sweeps
  }
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**sweeps** (\[object\])  
Identifier of the sweep.

**sweeps->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**sweeps->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**sweeps->created** (string)  
The datetime when the sweep occurred, in RFC 3339 format. Format: date-time

**sweeps->amount** (string)  
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

**sweeps->iso\_currency\_code** (string)  
The currency of the sweep, e.g. "USD".

**sweeps->settled** (nullable, string)  
The date when the sweep settled, in the YYYY-MM-DD format. Format: date

**sweeps->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: date

**sweeps->status** (nullable, string)  
The status of a sweep transfer "pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled. This is the terminal state of a successful credit sweep. "returned" - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. "funds\_available" - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. "failed" - The sweep has failed. This is the terminal state of a failed sweep. Possible values: pending, posted, settled, funds\_available, returned, failed, null

**sweeps->trigger** (nullable, string)  
The trigger of the sweep "manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance\_threshold" - The sweep is created by balance threshold setting "automatic\_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: manual, incoming, balance\_threshold, automatic\_aggregate

**sweeps->description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

**sweeps->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**sweeps->failure\_reason** (nullable, object)  
The failure reason if the status for a sweep is "failed" or "returned". Null value otherwise.

**sweeps->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the sweep status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**sweeps->failure\_reason->description** (nullable, string)  
A human-readable description of the reason for the failure or reversal.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "sweeps": [
    {
      "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
      "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a",
      "created": "2019-12-09T17:27:15Z",
      "amount": "-12.34",
      "iso_currency_code": "USD",
      "settled": "2019-12-10",
      "status": "settled",
      "originator_client_id": null
    }
  ],
  "request_id": "saKrIBuEB9qJZno"
}
```

### Webhooks 

\=\*=\*=\*=

#### TRANSFER\_EVENTS\_UPDATE 

Fired when new transfer events are available. Receiving this webhook indicates you should fetch the new events from [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) . If multiple transfer events occur within a single minute, only one webhook will be fired, so a single webhook instance may correspond to multiple transfer events.

#### Properties 

**webhook\_type** (string)  
TRANSFER

**webhook\_code** (string)  
TRANSFER\_EVENTS\_UPDATE

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSFER",
  "webhook_code": "TRANSFER_EVENTS_UPDATE",
  "environment": "production"
}
```

---


# API - Recurring Transfers | Plaid Docs

Recurring transfers 
====================

#### API reference for recurring transfer endpoints and webhooks 

\=\*=\*=\*=

#### Recurring transfers 

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

| Recurring Transfer endpoints |  |
| --- | --- |
| [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | Create a recurring transfer |
| [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) | Cancel a recurring transfer |
| [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) | Retrieve information about a recurring transfer |
| [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) | Retrieve a list of recurring transfers |

| Webhooks |  |
| --- | --- |
| [RECURRING\_CANCELLED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) | A recurring transfer has been cancelled by Plaid |
| [RECURRING\_NEW\_TRANSFER](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) | A new transfer of a recurring transfer has been originated |
| [RECURRING\_TRANSFER\_SKIPPED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_transfer_skipped) | An instance of a scheduled recurring transfer could not be created |

### Endpoints 

\=\*=\*=\*=

#### /transfer/recurring/create 

#### Create a recurring transfer 

Use the [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) endpoint to initiate a new recurring transfer. This capability is not currently supported for Transfer UI or Platform Payments (beta) customers.

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

**access\_token** (required, string)  
The Plaid access\_token for the account that will be debited or credited.

**idempotency\_key** (required, string)  
A random key provided by the client, per unique recurring transfer. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a recurring fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single recurring transfer is created. Max length: 50

**account\_id** (required, string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**type** (required, string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**network** (required, string)  
Networks eligible for recurring transfers. Possible values: ach, same-day-ach, rtp

**ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**amount** (required, string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**user\_present** (boolean)  
If the end user is initiating the specific transfer themselves via an interactive UI, this should be true; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false.

**description** (required, string)  
The description of the recurring transfer.

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. This field may only be used when using the sandbox environment. If provided, the created recurring\_transfer is associated with the test\_clock. New originations are automatically generated when the associated test\_clock advances. For more details, see Simulating recurring transfers.

**schedule** (required, object)  
The schedule that the recurring transfer will be executed on.

**schedule->interval\_unit** (required, string)  
The unit of the recurring interval. Possible values: week, monthMin length: 1

**schedule->interval\_count** (required, integer)  
The number of recurring interval\_units between originations. The recurring interval (before holiday adjustment) is calculated by multiplying interval\_unit and interval\_count. For example, to schedule a recurring transfer which originates once every two weeks, set interval\_unit = week and interval\_count = 2.

**schedule->interval\_execution\_day** (required, integer)  
The day of the interval on which to schedule the transfer. If the interval\_unit is week, interval\_execution\_day should be an integer from 1 (Monday) to 5 (Friday). If the interval\_unit is month, interval\_execution\_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day.

**schedule->start\_date** (required, string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval\_execution\_day on or after the start\_date. For rtp recurring transfers, start\_date must be in the future. Otherwise, if the first interval\_execution\_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**schedule->end\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval\_execution\_day on or before the end\_date. If the interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**user** (required, object)  
The legal name and other information for the account holder.

**user->legal\_name** (required, string)  
The user's legal name.

**user->phone\_number** (string)  
The user's phone number. Phone number input may be validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**user->email\_address** (string)  
The user's email address.

**user->address** (object)  
The address associated with the account holder.

**user->address->street** (string)  
The street number and name (i.e., "100 Market St.").

**user->address->city** (string)  
Ex. "San Francisco"

**user->address->region** (string)  
The state or province (e.g., "CA").

**user->address->postal\_code** (string)  
The postal code (e.g., "94103").

**user->address->country** (string)  
A two-letter country code (e.g., "US").

**device** (object)  
Information about the device being used to initiate the authorization.

**device->ip\_address** (required, string)  
The IP address of the device being used to initiate the authorization.

**device->user\_agent** (required, string)  
The user agent of the device being used to initiate the authorization.

```javascript
const request: TransferRecurringCreateRequest = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  type: 'credit',
  network: 'ach',
  amount: '12.34',
  ach_class: 'ppd',
  description: 'payment',
  idempotency_key: '12345',
  schedule: {
    start_date: '2022-10-01',
    end_date: '20223-10-01',
    interval_unit: 'week',
    interval_count: 1,
    interval_execution_day: 5
  }
  user: {
    legal_name: 'Anne Charleston',
  },
};


try {
  const response = await client.transferRecurringCreate(request);
  const recurringTransferId = response.data.recurring_transfer.recurring_transfer_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**recurring\_transfer** (nullable, object)  
Represents a recurring transfer within the Transfers API.

**recurring\_transfer->recurring\_transfer\_id** (string)  
Plaid’s unique identifier for a recurring transfer.

**recurring\_transfer->created** (string)  
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**recurring\_transfer->next\_origination\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). The next transfer origination date after bank holiday adjustment. Format: date

**recurring\_transfer->test\_clock\_id** (nullable, string)  
Plaid’s unique identifier for a test clock.

**recurring\_transfer->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**recurring\_transfer->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**recurring\_transfer->status** (string)  
The status of the recurring transfer. active: The recurring transfer is currently active. cancelled: The recurring transfer was cancelled by the client or Plaid. expired: The recurring transfer has completed all originations according to its recurring schedule. Possible values: active, cancelled, expired

**recurring\_transfer->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**recurring\_transfer->network** (string)  
Networks eligible for recurring transfers. Possible values: ach, same-day-ach, rtp

**recurring\_transfer->account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**recurring\_transfer->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**recurring\_transfer->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**recurring\_transfer->description** (string)  
The description of the recurring transfer.

**recurring\_transfer->transfer\_ids** (\[string\])  
The created transfer instances associated with this recurring\_transfer\_id. If the recurring transfer has been newly created, this array will be empty.

**recurring\_transfer->user** (object)  
The legal name and other information for the account holder.

**recurring\_transfer->user->legal\_name** (string)  
The user's legal name.

**recurring\_transfer->user->phone\_number** (nullable, string)  
The user's phone number.

**recurring\_transfer->user->email\_address** (nullable, string)  
The user's email address.

**recurring\_transfer->user->address** (nullable, object)  
The address associated with the account holder.

**recurring\_transfer->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**recurring\_transfer->user->address->city** (nullable, string)  
Ex. "San Francisco"

**recurring\_transfer->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**recurring\_transfer->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**recurring\_transfer->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**recurring\_transfer->schedule** (object)  
The schedule that the recurring transfer will be executed on.

**recurring\_transfer->schedule->interval\_unit** (string)  
The unit of the recurring interval. Possible values: week, monthMin length: 1

**recurring\_transfer->schedule->interval\_count** (integer)  
The number of recurring interval\_units between originations. The recurring interval (before holiday adjustment) is calculated by multiplying interval\_unit and interval\_count. For example, to schedule a recurring transfer which originates once every two weeks, set interval\_unit = week and interval\_count = 2.

**recurring\_transfer->schedule->interval\_execution\_day** (integer)  
The day of the interval on which to schedule the transfer. If the interval\_unit is week, interval\_execution\_day should be an integer from 1 (Monday) to 5 (Friday). If the interval\_unit is month, interval\_execution\_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day.

**recurring\_transfer->schedule->start\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval\_execution\_day on or after the start\_date. For rtp recurring transfers, start\_date must be in the future. Otherwise, if the first interval\_execution\_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**recurring\_transfer->schedule->end\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval\_execution\_day on or before the end\_date. If the interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**decision** (string)  
A decision regarding the proposed transfer. approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision\_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended. Refer to the code field in the decision\_rationale object for details. declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision\_rationale object for details. user\_action\_required – An action is required before Plaid can assess the transfer risk and make a decision. The most common scenario is to update authentication for an Item. To complete the required action, initialize Link by setting transfer.authorization\_id in the request of /link/token/create. After Link flow is completed, you may re-attempt the authorization request. Possible values: approved, declined, user\_action\_required

**decision\_rationale** (nullable, object)  
The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.

**decision\_rationale->code** (string)  
A code representing the rationale for approving or declining the proposed transfer. If the rationale\_code is null, the transfer passed the authorization check. Any non-null value for an approved transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved transfer are: MANUALLY\_VERIFIED\_ITEM – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. ITEM\_LOGIN\_REQUIRED – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting transfer.authorization\_id in the request to /link/token/create. MIGRATED\_ACCOUNT\_ITEM - Item created via /transfer/migrate\_account endpoint, limited information available. ERROR – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was declined: NSF – Transaction likely to result in a return due to insufficient funds. RISK - Transaction is high-risk. TRANSFER\_LIMIT\_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying description field to understand which limit has been reached. Possible values: NSF, RISK, TRANSFER\_LIMIT\_REACHED, MANUALLY\_VERIFIED\_ITEM, ITEM\_LOGIN\_REQUIRED, PAYMENT\_PROFILE\_LOGIN\_REQUIRED, ERROR, MIGRATED\_ACCOUNT\_ITEM, null

**decision\_rationale->description** (string)  
A human-readable description of the code associated with a transfer approval or transfer decline.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "recurring_transfer": {
    "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "created": "2022-07-05T12:48:37Z",
    "next_origination_date": "2022-10-28",
    "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
    "status": "active",
    "amount": "12.34",
    "description": "payment",
    "type": "debit",
    "ach_class": "ppd",
    "network": "ach",
    "origination_account_id": "",
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "iso_currency_code": "USD",
    "transfer_ids": [],
    "user": {
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128",
      "email_address": "acharleston@email.com",
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94053",
        "country": "US"
      }
    },
    "schedule": {
      "start_date": "2022-10-01",
      "end_date": "2023-10-01",
      "interval_unit": "week",
      "interval_count": 1,
      "interval_execution_day": 5
    }
  },
  "decision": "approved",
  "decision_rationale": null,
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/recurring/cancel 

#### Cancel a recurring transfer. 

Use the [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) endpoint to cancel a recurring transfer. Scheduled transfer that hasn't been submitted to bank will be cancelled.

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

**recurring\_transfer\_id** (required, string)  
Plaid’s unique identifier for a recurring transfer.

```javascript
const request: TransferRecurringCancelRequest = {
  recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};


try {
  const response = await client.transferRecurringCancel(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/recurring/get 

#### Retrieve a recurring transfer 

The [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) fetches information about the recurring transfer corresponding to the given `recurring_transfer_id`.

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

**recurring\_transfer\_id** (required, string)  
Plaid’s unique identifier for a recurring transfer.

```javascript
const request: TransferRecurringGetRequest = {
  recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};


try {
  const response = await client.transferRecurringGet(request);
  const recurringTransferId =
    response.data.recurring_transfer.recurring_transfer_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**recurring\_transfer** (object)  
Represents a recurring transfer within the Transfers API.

**recurring\_transfer->recurring\_transfer\_id** (string)  
Plaid’s unique identifier for a recurring transfer.

**recurring\_transfer->created** (string)  
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**recurring\_transfer->next\_origination\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). The next transfer origination date after bank holiday adjustment. Format: date

**recurring\_transfer->test\_clock\_id** (nullable, string)  
Plaid’s unique identifier for a test clock.

**recurring\_transfer->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**recurring\_transfer->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**recurring\_transfer->status** (string)  
The status of the recurring transfer. active: The recurring transfer is currently active. cancelled: The recurring transfer was cancelled by the client or Plaid. expired: The recurring transfer has completed all originations according to its recurring schedule. Possible values: active, cancelled, expired

**recurring\_transfer->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**recurring\_transfer->network** (string)  
Networks eligible for recurring transfers. Possible values: ach, same-day-ach, rtp

**recurring\_transfer->account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**recurring\_transfer->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**recurring\_transfer->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**recurring\_transfer->description** (string)  
The description of the recurring transfer.

**recurring\_transfer->transfer\_ids** (\[string\])  
The created transfer instances associated with this recurring\_transfer\_id. If the recurring transfer has been newly created, this array will be empty.

**recurring\_transfer->user** (object)  
The legal name and other information for the account holder.

**recurring\_transfer->user->legal\_name** (string)  
The user's legal name.

**recurring\_transfer->user->phone\_number** (nullable, string)  
The user's phone number.

**recurring\_transfer->user->email\_address** (nullable, string)  
The user's email address.

**recurring\_transfer->user->address** (nullable, object)  
The address associated with the account holder.

**recurring\_transfer->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**recurring\_transfer->user->address->city** (nullable, string)  
Ex. "San Francisco"

**recurring\_transfer->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**recurring\_transfer->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**recurring\_transfer->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**recurring\_transfer->schedule** (object)  
The schedule that the recurring transfer will be executed on.

**recurring\_transfer->schedule->interval\_unit** (string)  
The unit of the recurring interval. Possible values: week, monthMin length: 1

**recurring\_transfer->schedule->interval\_count** (integer)  
The number of recurring interval\_units between originations. The recurring interval (before holiday adjustment) is calculated by multiplying interval\_unit and interval\_count. For example, to schedule a recurring transfer which originates once every two weeks, set interval\_unit = week and interval\_count = 2.

**recurring\_transfer->schedule->interval\_execution\_day** (integer)  
The day of the interval on which to schedule the transfer. If the interval\_unit is week, interval\_execution\_day should be an integer from 1 (Monday) to 5 (Friday). If the interval\_unit is month, interval\_execution\_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day.

**recurring\_transfer->schedule->start\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval\_execution\_day on or after the start\_date. For rtp recurring transfers, start\_date must be in the future. Otherwise, if the first interval\_execution\_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**recurring\_transfer->schedule->end\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval\_execution\_day on or before the end\_date. If the interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "recurring_transfer": {
    "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "created": "2022-07-05T12:48:37Z",
    "next_origination_date": "2022-10-28",
    "test_clock_id": null,
    "status": "active",
    "amount": "12.34",
    "description": "payment",
    "type": "debit",
    "ach_class": "ppd",
    "network": "ach",
    "origination_account_id": "",
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "iso_currency_code": "USD",
    "transfer_ids": [
      "271ef220-dbf8-caeb-a7dc-a2b3e8a80963",
      "c8dbaf75-2abb-e2dc-4171-12448e13b848"
    ],
    "user": {
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128",
      "email_address": "acharleston@email.com",
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94053",
        "country": "US"
      }
    },
    "schedule": {
      "start_date": "2022-10-01",
      "end_date": "2023-10-01",
      "interval_unit": "week",
      "interval_count": 1,
      "interval_execution_day": 5
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/recurring/list 

#### List recurring transfers 

Use the [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) endpoint to see a list of all your recurring transfers and their statuses. Results are paginated; use the `count` and `offset` query parameters to retrieve the desired recurring transfers.

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

**start\_time** (string)  
The start created datetime of recurring transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**end\_time** (string)  
The end created datetime of recurring transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**count** (integer)  
The maximum number of recurring transfers to return. Minimum: 1 Maximum: 25 Default: 25

**offset** (integer)  
The number of recurring transfers to skip before returning results. Default: 0 Minimum: 0

**funding\_account\_id** (string)  
Filter recurring transfers to only those with the specified funding\_account\_id.

```javascript
const request: TransferRecurringListRequest = {
  start_time: '2022-09-29T20:35:49Z',
  end_time: '2022-10-29T20:35:49Z',
  count: 1,
};


try {
  const response = await client.transferRecurringList(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**recurring\_transfers** (\[object\])  
Plaid’s unique identifier for a recurring transfer.

**recurring\_transfers->created** (string)  
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**recurring\_transfers->next\_origination\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). The next transfer origination date after bank holiday adjustment. Format: date

**recurring\_transfers->test\_clock\_id** (nullable, string)  
Plaid’s unique identifier for a test clock.

**recurring\_transfers->type** (string)  
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account. Possible values: debit, credit

**recurring\_transfers->amount** (string)  
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization\_id will be sent.

**recurring\_transfers->status** (string)  
The status of the recurring transfer. active: The recurring transfer is currently active. cancelled: The recurring transfer was cancelled by the client or Plaid. expired: The recurring transfer has completed all originations according to its recurring schedule. Possible values: active, cancelled, expired

**recurring\_transfers->ach\_class** (string)  
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: ccd, ppd Codes supported for debits: ccd, tel, web "ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts "ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. "web" - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. "tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: ccd, ppd, tel, web

**recurring\_transfers->network** (string)  
Networks eligible for recurring transfers. Possible values: ach, same-day-ach, rtp

**recurring\_transfers->account\_id** (string)  
The Plaid account\_id corresponding to the end-user account that will be debited or credited.

**recurring\_transfers->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**recurring\_transfers->iso\_currency\_code** (string)  
The currency of the transfer amount, e.g. "USD"

**recurring\_transfers->description** (string)  
The description of the recurring transfer.

**recurring\_transfers->transfer\_ids** (\[string\])  
The created transfer instances associated with this recurring\_transfer\_id. If the recurring transfer has been newly created, this array will be empty.

**recurring\_transfers->user** (object)  
The legal name and other information for the account holder.

**recurring\_transfers->user->legal\_name** (string)  
The user's legal name.

**recurring\_transfers->user->phone\_number** (nullable, string)  
The user's phone number.

**recurring\_transfers->user->email\_address** (nullable, string)  
The user's email address.

**recurring\_transfers->user->address** (nullable, object)  
The address associated with the account holder.

**recurring\_transfers->user->address->street** (nullable, string)  
The street number and name (i.e., "100 Market St.").

**recurring\_transfers->user->address->city** (nullable, string)  
Ex. "San Francisco"

**recurring\_transfers->user->address->region** (nullable, string)  
The state or province (e.g., "CA").

**recurring\_transfers->user->address->postal\_code** (nullable, string)  
The postal code (e.g., "94103").

**recurring\_transfers->user->address->country** (nullable, string)  
A two-letter country code (e.g., "US").

**recurring\_transfers->schedule** (object)  
The schedule that the recurring transfer will be executed on.

**recurring\_transfers->schedule->interval\_unit** (string)  
The unit of the recurring interval. Possible values: week, monthMin length: 1

**recurring\_transfers->schedule->interval\_count** (integer)  
The number of recurring interval\_units between originations. The recurring interval (before holiday adjustment) is calculated by multiplying interval\_unit and interval\_count. For example, to schedule a recurring transfer which originates once every two weeks, set interval\_unit = week and interval\_count = 2.

**recurring\_transfers->schedule->interval\_execution\_day** (integer)  
The day of the interval on which to schedule the transfer. If the interval\_unit is week, interval\_execution\_day should be an integer from 1 (Monday) to 5 (Friday). If the interval\_unit is month, interval\_execution\_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day.

**recurring\_transfers->schedule->start\_date** (string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval\_execution\_day on or after the start\_date. For rtp recurring transfers, start\_date must be in the future. Otherwise, if the first interval\_execution\_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so. Format: date

**recurring\_transfers->schedule->end\_date** (nullable, string)  
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval\_execution\_day on or before the end\_date. If the interval\_execution\_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so. Format: date

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "recurring_transfers": [
    {
      "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "created": "2022-07-05T12:48:37Z",
      "next_origination_date": "2022-10-28",
      "test_clock_id": null,
      "status": "active",
      "amount": "12.34",
      "description": "payment",
      "type": "debit",
      "ach_class": "ppd",
      "network": "ach",
      "origination_account_id": "",
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
      "iso_currency_code": "USD",
      "transfer_ids": [
        "4242fc8d-3ec6-fb38-fa0c-a8e37d03cd57"
      ],
      "user": {
        "legal_name": "Anne Charleston",
        "phone_number": "510-555-0128",
        "email_address": "acharleston@email.com",
        "address": {
          "street": "123 Main St.",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94053",
          "country": "US"
        }
      },
      "schedule": {
        "start_date": "2022-10-01",
        "end_date": "2023-10-01",
        "interval_unit": "week",
        "interval_count": 1,
        "interval_execution_day": 5
      }
    }
  ],
  "request_id": "saKrIBuEB9qJZno"
}
```

### Webhooks 

\=\*=\*=\*=

#### RECURRING\_NEW\_TRANSFER 

Fired when a new transfer of a recurring transfer is originated.

#### Properties 

**webhook\_type** (string)  
TRANSFER

**webhook\_code** (string)  
RECURRING\_NEW\_TRANSFER

**recurring\_transfer\_id** (string)  
Plaid’s unique identifier for a recurring transfer.

**transfer\_id** (string)  
Plaid’s unique identifier for a transfer.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSFER",
  "webhook_code": "RECURRING_NEW_TRANSFER",
  "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "transfer_id": "271ef220-dbf8-caeb-a7dc-a2b3e8a80963",
  "environment": "production"
}
```

\=\*=\*=\*=

#### RECURRING\_TRANSFER\_SKIPPED 

Fired when Plaid is unable to originate a new ACH transaction of the recurring transfer on the planned date.

#### Properties 

**webhook\_type** (string)  
TRANSFER

**webhook\_code** (string)  
RECURRING\_TRANSFER\_SKIPPED

**recurring\_transfer\_id** (string)  
Plaid’s unique identifier for a recurring transfer.

**authorization\_decision** (string)  
A decision regarding the proposed transfer. approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision\_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended. Refer to the code field in the decision\_rationale object for details. declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision\_rationale object for details. user\_action\_required – An action is required before Plaid can assess the transfer risk and make a decision. The most common scenario is to update authentication for an Item. To complete the required action, initialize Link by setting transfer.authorization\_id in the request of /link/token/create. After Link flow is completed, you may re-attempt the authorization request. Possible values: approved, declined, user\_action\_required

**authorization\_decision\_rationale\_code** (string)  
A code representing the rationale for approving or declining the proposed transfer. If the rationale\_code is null, the transfer passed the authorization check. Any non-null value for an approved transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved transfer are: MANUALLY\_VERIFIED\_ITEM – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. ITEM\_LOGIN\_REQUIRED – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting transfer.authorization\_id in the request to /link/token/create. MIGRATED\_ACCOUNT\_ITEM - Item created via /transfer/migrate\_account endpoint, limited information available. ERROR – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was declined: NSF – Transaction likely to result in a return due to insufficient funds. RISK - Transaction is high-risk. TRANSFER\_LIMIT\_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying description field to understand which limit has been reached. Possible values: NSF, RISK, TRANSFER\_LIMIT\_REACHED, MANUALLY\_VERIFIED\_ITEM, ITEM\_LOGIN\_REQUIRED, PAYMENT\_PROFILE\_LOGIN\_REQUIRED, ERROR, MIGRATED\_ACCOUNT\_ITEM, null

**skipped\_origination\_date** (string)  
The planned date on which Plaid is unable to originate a new ACH transaction of the recurring transfer. This will be of the form YYYY-MM-DD. Format: date

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSFER",
  "webhook_code": "RECURRING_TRANSFER_SKIPPED",
  "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "authorization_decision": "declined",
  "authorization_decision_rationale_code": "NSF",
  "skipped_origination_date": "2022-11-30",
  "environment": "production"
}
```

\=\*=\*=\*=

#### RECURRING\_CANCELLED 

Fired when a recurring transfer is cancelled by Plaid.

#### Properties 

**webhook\_type** (string)  
TRANSFER

**webhook\_code** (string)  
RECURRING\_CANCELLED

**recurring\_transfer\_id** (string)  
Plaid’s unique identifier for a recurring transfer.

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "TRANSFER",
  "webhook_code": "RECURRING_CANCELLED",
  "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "environment": "production"
}
```

---


# API - Refunds | Plaid Docs

Transfer refunds 
=================

#### API reference for refunding transfers 

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

| Refunds |  |
| --- | --- |
| [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | Create a refund for a transfer |
| [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) | Cancel a refund |
| [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) | Retrieve information about a refund |

\=\*=\*=\*=

#### /transfer/refund/create 

#### Create a refund 

Use the [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) endpoint to create a refund for a transfer. A transfer can be refunded if the transfer was initiated in the past 180 days.  
Refunds come out of the available balance of the ledger used for the original debit transfer. If there are not enough funds in the available balance to cover the refund amount, the refund will be rejected. You can create a refund at any time. Plaid does not impose any hold time on refunds.

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

**transfer\_id** (required, string)  
The ID of the transfer to refund.

**amount** (required, string)  
The amount of the refund (decimal string with two digits of precision e.g. "10.00").

**idempotency\_key** (required, string)  
A random key provided by the client, per unique refund. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a refund fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single refund is created. Max length: 50

```javascript
const request: TransferRefundCreateRequest = {
  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
  amount: '12.34',
  idempotency_key: 'VEK2ea3X6LKywsc8J6pg',
};


try {
  const response = await client.transferRefundCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**refund** (object)  
Represents a refund within the Transfers API.

**refund->id** (string)  
Plaid’s unique identifier for a refund.

**refund->transfer\_id** (string)  
The ID of the transfer to refund.

**refund->amount** (string)  
The amount of the refund (decimal string with two digits of precision e.g. "10.00").

**refund->status** (string)  
The status of the refund. pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned. Possible values: pending, posted, cancelled, failed, settled, returned

**refund->failure\_reason** (nullable, object)  
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

**refund->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the refund status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**refund->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors. This field is deprecated in favor of the more versatile failure\_code, which encompasses non-ACH failure codes as well.

**refund->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**refund->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**refund->created** (string)  
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**refund->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "refund": {
    "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",
    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "amount": "12.34",
    "status": "pending",
    "created": "2020-08-06T17:27:15Z",
    "failure_reason": null,
    "network_trace_id": null
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/refund/cancel 

#### Cancel a refund 

Use the [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) endpoint to cancel a refund. A refund is eligible for cancellation if it has not yet been submitted to the payment network.

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

**refund\_id** (required, string)  
Plaid’s unique identifier for a refund.

```javascript
const request: TransferRefundCancelRequest = {
  refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};


try {
  const response = await client.transferRefundCancel(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "saKrIBuEB9qJZno"
}
```

\=\*=\*=\*=

#### /transfer/refund/get 

#### Retrieve a refund 

The [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) endpoint fetches information about the refund corresponding to the given `refund_id`.

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

**refund\_id** (required, string)  
Plaid’s unique identifier for a refund.

```javascript
const request: TransferRefundGetRequest = {
  refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};


try {
  const response = await client.transferRefundGet(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**refund** (object)  
Represents a refund within the Transfers API.

**refund->id** (string)  
Plaid’s unique identifier for a refund.

**refund->transfer\_id** (string)  
The ID of the transfer to refund.

**refund->amount** (string)  
The amount of the refund (decimal string with two digits of precision e.g. "10.00").

**refund->status** (string)  
The status of the refund. pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned. Possible values: pending, posted, cancelled, failed, settled, returned

**refund->failure\_reason** (nullable, object)  
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

**refund->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the refund status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**refund->failure\_reason->ach\_return\_code** (deprecated, nullable, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors. This field is deprecated in favor of the more versatile failure\_code, which encompasses non-ACH failure codes as well.

**refund->failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**refund->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**refund->created** (string)  
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z Format: date-time

**refund->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "refund": {
    "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",
    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "amount": "12.34",
    "status": "pending",
    "created": "2020-08-06T17:27:15Z",
    "failure_reason": null,
    "network_trace_id": null
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

---


# API - Virtual Accounts | Plaid Docs

Virtual Accounts (UK and Europe) 
=================================

#### API reference for Virtual Accounts endpoints and webhooks 

Manage the entire lifecycle of a payment. For how-to guidance, see the [Virtual Accounts documentation](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) | Create a virtual account |
| [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) | Fetch a virtual account |
| [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) | List all virtual accounts |
| [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) | Execute a transaction |
| [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) | Fetch a transaction |
| [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) | List all transactions |

| See also |  |
| --- | --- |
| [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | Refund a payment from a virtual account |

| Webhooks |  |
| --- | --- |
| [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) | The status of a transaction has changed |

### Endpoints 

\=\*=\*=\*=

#### /wallet/create 

#### Create an e-wallet 

Create an e-wallet. The response is the newly created e-wallet object.

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

**iso\_currency\_code** (required, string)  
An ISO-4217 currency code, used with e-wallets and transactions. Possible values: GBP, EURMin length: 3 Max length: 3

```javascript
const request: WalletCreateRequest = {
  iso_currency_code: isoCurrencyCode,
};
try {
  const response = await plaidClient.walletCreate(request);
  const walletID = response.data.wallet_id;
  const balance = response.data.balance;
  const numbers = response.data.numbers;
  const recipientID = response.data.recipient_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**wallet\_id** (string)  
A unique ID identifying the e-wallet

**balance** (object)  
An object representing the e-wallet balance

**balance->iso\_currency\_code** (string)  
The ISO-4217 currency code of the balance

**balance->current** (number)  
The total amount of funds in the account Format: double

**balance->available** (number)  
The total amount of funds in the account after subtracting pending debit transaction amounts Format: double

**numbers** (object)  
An object representing the e-wallet account numbers

**numbers->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.

**numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**numbers->international->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**numbers->international->bic** (string)  
The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: 8 Max length: 11

**recipient\_id** (string)  
The ID of the recipient that corresponds to the e-wallet account numbers

**status** (string)  
The status of the wallet. UNKNOWN: The wallet status is unknown. ACTIVE: The wallet is active and ready to send money to and receive money from. CLOSED: The wallet is closed. Any transactions made to or from this wallet will error. Possible values: UNKNOWN, ACTIVE, CLOSED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
  "balance": {
    "iso_currency_code": "GBP",
    "current": 123.12,
    "available": 100.96
  },
  "request_id": "4zlKapIkTm8p5KM",
  "numbers": {
    "bacs": {
      "account": "12345678",
      "sort_code": "123456"
    }
  },
  "status": "ACTIVE"
}
```

\=\*=\*=\*=

#### /wallet/get 

#### Fetch an e-wallet 

Fetch an e-wallet. The response includes the current balance.

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

**wallet\_id** (required, string)  
The ID of the e-wallet Min length: 1

```javascript
const request: WalletGetRequest = {
  wallet_id: walletID,
};
try {
  const response = await plaidClient.walletGet(request);
  const walletID = response.data.wallet_id;
  const balance = response.data.balance;
  const numbers = response.data.numbers;
  const recipientID = response.data.recipient_id;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**wallet\_id** (string)  
A unique ID identifying the e-wallet

**balance** (object)  
An object representing the e-wallet balance

**balance->iso\_currency\_code** (string)  
The ISO-4217 currency code of the balance

**balance->current** (number)  
The total amount of funds in the account Format: double

**balance->available** (number)  
The total amount of funds in the account after subtracting pending debit transaction amounts Format: double

**numbers** (object)  
An object representing the e-wallet account numbers

**numbers->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.

**numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**numbers->international->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**numbers->international->bic** (string)  
The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: 8 Max length: 11

**recipient\_id** (string)  
The ID of the recipient that corresponds to the e-wallet account numbers

**status** (string)  
The status of the wallet. UNKNOWN: The wallet status is unknown. ACTIVE: The wallet is active and ready to send money to and receive money from. CLOSED: The wallet is closed. Any transactions made to or from this wallet will error. Possible values: UNKNOWN, ACTIVE, CLOSED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
  "balance": {
    "iso_currency_code": "GBP",
    "current": 123.12,
    "available": 100.96
  },
  "request_id": "4zlKapIkTm8p5KM",
  "numbers": {
    "bacs": {
      "account": "12345678",
      "sort_code": "123456"
    },
    "international": {
      "iban": "GB33BUKB20201555555555",
      "bic": "BUKBGB22"
    }
  },
  "status": "ACTIVE"
}
```

\=\*=\*=\*=

#### /wallet/list 

#### Fetch a list of e-wallets 

This endpoint lists all e-wallets in descending order of creation.

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

**iso\_currency\_code** (string)  
An ISO-4217 currency code, used with e-wallets and transactions. Possible values: GBP, EURMin length: 3 Max length: 3

**cursor** (string)  
A base64 value representing the latest e-wallet that has already been requested. Set this to next\_cursor received from the previous /wallet/list request. If provided, the response will only contain e-wallets created before that e-wallet. If omitted, the response will contain e-wallets starting from the most recent, and in descending order. Max length: 1024

**count** (integer)  
The number of e-wallets to fetch Minimum: 1 Maximum: 20 Default: 10

```javascript
const request: WalletListRequest = {
  iso_currency_code: 'GBP',
  count: 10,
};
try {
  const response = await plaidClient.walletList(request);
  const wallets = response.data.wallets;
  const nextCursor = response.data.next_cursor;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**wallets** (\[object\])  
An array of e-wallets

**wallets->wallet\_id** (string)  
A unique ID identifying the e-wallet

**wallets->balance** (object)  
An object representing the e-wallet balance

**wallets->balance->iso\_currency\_code** (string)  
The ISO-4217 currency code of the balance

**wallets->balance->current** (number)  
The total amount of funds in the account Format: double

**wallets->balance->available** (number)  
The total amount of funds in the account after subtracting pending debit transaction amounts Format: double

**wallets->numbers** (object)  
An object representing the e-wallet account numbers

**wallets->numbers->bacs** (nullable, object)  
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.

**wallets->numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**wallets->numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**wallets->numbers->international** (nullable, object)  
Account numbers using the International Bank Account Number and BIC/SWIFT code format.

**wallets->numbers->international->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**wallets->numbers->international->bic** (string)  
The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: 8 Max length: 11

**wallets->recipient\_id** (string)  
The ID of the recipient that corresponds to the e-wallet account numbers

**wallets->status** (string)  
The status of the wallet. UNKNOWN: The wallet status is unknown. ACTIVE: The wallet is active and ready to send money to and receive money from. CLOSED: The wallet is closed. Any transactions made to or from this wallet will error. Possible values: UNKNOWN, ACTIVE, CLOSED

**next\_cursor** (string)  
Cursor used for fetching e-wallets created before the latest e-wallet provided in this response

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "wallets": [
    {
      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
      "balance": {
        "iso_currency_code": "GBP",
        "current": 123.12,
        "available": 100.96
      },
      "numbers": {
        "bacs": {
          "account": "12345678",
          "sort_code": "123456"
        }
      },
      "status": "ACTIVE"
    },
    {
      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a999",
      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f7",
      "balance": {
        "iso_currency_code": "EUR",
        "current": 456.78,
        "available": 100.96
      },
      "numbers": {
        "international": {
          "iban": "GB22HBUK40221241555626",
          "bic": "HBUKGB4B"
        }
      },
      "status": "ACTIVE"
    }
  ],
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /wallet/transaction/execute 

#### Execute a transaction using an e-wallet 

Execute a transaction using the specified e-wallet. Specify the e-wallet to debit from, the counterparty to credit to, the idempotency key to prevent duplicate transactions, the amount and reference for the transaction. Transactions will settle in seconds to several days, depending on the underlying payment rail.

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

**idempotency\_key** (required, string)  
A random key provided by the client, per unique wallet transaction. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed. Max length: 128 Min length: 1

**wallet\_id** (required, string)  
The ID of the e-wallet to debit from Min length: 1

**counterparty** (required, object)  
An object representing the e-wallet transaction's counterparty

**counterparty->name** (required, string)  
The name of the counterparty Min length: 1

**counterparty->numbers** (required, object)  
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.

**counterparty->numbers->bacs** (object)  
The account number and sort code of the counterparty's account

**counterparty->numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**counterparty->numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**counterparty->numbers->international** (object)  
International Bank Account Number for a Wallet Transaction

**counterparty->numbers->international->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**counterparty->address** (object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**counterparty->address->street** (required, \[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**counterparty->address->city** (required, string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**counterparty->address->postal\_code** (required, string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**counterparty->address->country** (required, string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**counterparty->date\_of\_birth** (string)  
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format. Format: date

**amount** (required, object)  
The amount and currency of a transaction

**amount->iso\_currency\_code** (required, string)  
An ISO-4217 currency code, used with e-wallets and transactions. Possible values: GBP, EURMin length: 3 Max length: 3

**amount->value** (required, number)  
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23. Format: double Minimum: 0.01

**reference** (required, string)  
A reference for the transaction. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces. Ensure that the reference field is unique for each transaction. Max length: 18 Min length: 6

**originating\_fund\_source** (object)  
The original source of the funds. This field is required by local regulation for certain businesses (e.g. money remittance) to send payouts to recipients in the EU and UK.

**originating\_fund\_source->full\_name** (required, string)  
The full name associated with the source of the funds.

**originating\_fund\_source->address** (required, object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**originating\_fund\_source->address->street** (required, \[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**originating\_fund\_source->address->city** (required, string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**originating\_fund\_source->address->postal\_code** (required, string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**originating\_fund\_source->address->country** (required, string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**originating\_fund\_source->account\_number** (required, string)  
The account number from which the funds are sourced.

**originating\_fund\_source->bic** (required, string)  
The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: 8 Max length: 11

```javascript
const request: WalletTransactionExecuteRequest = {
  wallet_id: walletID,
  counterparty: {
    name: 'Test',
    numbers: {
      bacs: {
        account: '12345678',
        sort_code: '123456',
      },
    },
  },
  amount: {
    value: 1,
    iso_currency_code: 'GBP',
  },
  reference: 'transaction ABC123',
  idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753',
};
try {
  const response = await plaidClient.walletTransactionExecute(request);
  const transactionID = response.data.transaction_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transaction\_id** (string)  
A unique ID identifying the transaction

**status** (string)  
The status of the transaction. AUTHORISING: The transaction is being processed for validation and compliance. INITIATED: The transaction has been initiated and is currently being processed. EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. FAILED: The transaction failed to process successfully. This is a terminal status. BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transaction_id": "wallet-transaction-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
  "status": "EXECUTED",
  "request_id": "4zlKapIkTm8p5KM"
}
```

\=\*=\*=\*=

#### /wallet/transaction/get 

#### Fetch an e-wallet transaction 

Fetch a specific e-wallet transaction

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

**transaction\_id** (required, string)  
The ID of the transaction to fetch Min length: 1

```javascript
const request: WalletTransactionGetRequest = {
  transaction_id: transactionID,
};
try {
  const response = await plaidClient.walletTransactionGet(request);
  const transactionID = response.data.transaction_id;
  const reference = response.data.reference;
  const type = response.data.type;
  const amount = response.data.amount;
  const counterparty = response.data.counterparty;
  const status = response.data.status;
  const createdAt = response.created_at;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transaction\_id** (string)  
A unique ID identifying the transaction

**wallet\_id** (string)  
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.

**reference** (string)  
A reference for the transaction

**type** (string)  
The type of the transaction. The supported transaction types that are returned are: BANK\_TRANSFER: a transaction which credits an e-wallet through an external bank transfer. PAYOUT: a transaction which debits an e-wallet by disbursing funds to a counterparty. PIS\_PAY\_IN: a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the Payment Initiation endpoints. REFUND: a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's PIS APIs. FUNDS\_SWEEP: an automated transaction which debits funds from an e-wallet to a designated client-owned account. RETURN: an automated transaction where a debit transaction was reversed and money moved back to originating account. RECALL: a transaction where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment. Possible values: BANK\_TRANSFER, PAYOUT, PIS\_PAY\_IN, REFUND, FUNDS\_SWEEP, RETURN, RECALL

**scheme** (nullable, string)  
The payment scheme used to execute this transaction. This is present only for transaction types PAYOUT and REFUND. FASTER\_PAYMENTS: The standard payment scheme within the UK. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment to a beneficiary within the SEPA area. Possible values: null, FASTER\_PAYMENTS, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

**amount** (object)  
The amount and currency of a transaction

**amount->iso\_currency\_code** (string)  
An ISO-4217 currency code, used with e-wallets and transactions. Possible values: GBP, EURMin length: 3 Max length: 3

**amount->value** (number)  
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23. Format: double Minimum: 0.01

**counterparty** (object)  
An object representing the e-wallet transaction's counterparty

**counterparty->name** (string)  
The name of the counterparty Min length: 1

**counterparty->numbers** (object)  
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.

**counterparty->numbers->bacs** (nullable, object)  
The account number and sort code of the counterparty's account

**counterparty->numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**counterparty->numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**counterparty->numbers->international** (nullable, object)  
International Bank Account Number for a Wallet Transaction

**counterparty->numbers->international->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**counterparty->address** (nullable, object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**counterparty->address->street** (\[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**counterparty->address->city** (string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**counterparty->address->postal\_code** (string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**counterparty->address->country** (string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**counterparty->date\_of\_birth** (nullable, string)  
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format. Format: date

**status** (string)  
The status of the transaction. AUTHORISING: The transaction is being processed for validation and compliance. INITIATED: The transaction has been initiated and is currently being processed. EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. FAILED: The transaction failed to process successfully. This is a terminal status. BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED

**created\_at** (string)  
Timestamp when the transaction was created, in ISO 8601 format. Format: date-time

**last\_status\_update** (string)  
The date and time of the last time the status was updated, in IS0 8601 format Format: date-time

**payment\_id** (nullable, string)  
The payment id that this transaction is associated with, if any. This is present only for transaction types PIS\_PAY\_IN and REFUND.

**failure\_reason** (nullable, string)  
The error code of a failed transaction. Error codes include: EXTERNAL\_SYSTEM: The transaction was declined by an external system. EXPIRED: The transaction request has expired. CANCELLED: The transaction request was rescinded. INVALID: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. UNKNOWN: The transaction was unsuccessful, but the exact cause is unknown. Possible values: EXTERNAL\_SYSTEM, EXPIRED, CANCELLED, INVALID, UNKNOWN

**error** (nullable, 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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->error\_code\_reason** (nullable, 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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (nullable, 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.

**error->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.

**error->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.

**error->status** (nullable, 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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**related\_transactions** (\[object\])  
A list of wallet transactions that this transaction is associated with, if any.

**related\_transactions->id** (string)  
The ID of the related transaction.

**related\_transactions->type** (string)  
The type of the transaction. Possible values: PAYOUT, RETURN, REFUND, FUNDS\_SWEEP

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
  "type": "PAYOUT",
  "reference": "Payout 99744",
  "amount": {
    "iso_currency_code": "GBP",
    "value": 123.12
  },
  "status": "EXECUTED",
  "created_at": "2020-12-02T21:14:54Z",
  "last_status_update": "2020-12-02T21:15:01Z",
  "counterparty": {
    "numbers": {
      "bacs": {
        "account": "31926819",
        "sort_code": "601613"
      }
    },
    "name": "John Smith"
  },
  "request_id": "4zlKapIkTm8p5KM",
  "related_transactions": [
    {
      "id": "wallet-transaction-id-sandbox-2ba30780-d549-4335-b1fe-c2a938aa39d2",
      "type": "RETURN"
    }
  ]
}
```

\=\*=\*=\*=

#### /wallet/transaction/list 

#### List e-wallet transactions 

This endpoint lists the latest transactions of the specified e-wallet. Transactions are returned in descending order by the `created_at` time.

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

**wallet\_id** (required, string)  
The ID of the e-wallet to fetch transactions from Min length: 1

**cursor** (string)  
A value representing the latest transaction to be included in the response. Set this from next\_cursor received in the previous /wallet/transaction/list request. If provided, the response will only contain that transaction and transactions created before it. If omitted, the response will contain transactions starting from the most recent, and in descending order by the created\_at time. Max length: 256

**count** (integer)  
The number of transactions to fetch Minimum: 1 Maximum: 200 Default: 10

**options** (object)  
Additional wallet transaction options

**options->start\_time** (string)  
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date. Format: date-time

**options->end\_time** (string)  
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date. Format: date-time

```javascript
const request: WalletTransactionListRequest = {
  wallet_id: walletID,
  count: 10,
};
try {
  const response = await plaidClient.walletTransactionList(request);
  const transactions = response.data.transactions;
  const nextCursor = response.data.next_cursor;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**transactions** (\[object\])  
An array of transactions of an e-wallet, associated with the given wallet\_id

**transactions->transaction\_id** (string)  
A unique ID identifying the transaction

**transactions->wallet\_id** (string)  
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.

**transactions->reference** (string)  
A reference for the transaction

**transactions->type** (string)  
The type of the transaction. The supported transaction types that are returned are: BANK\_TRANSFER: a transaction which credits an e-wallet through an external bank transfer. PAYOUT: a transaction which debits an e-wallet by disbursing funds to a counterparty. PIS\_PAY\_IN: a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the Payment Initiation endpoints. REFUND: a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's PIS APIs. FUNDS\_SWEEP: an automated transaction which debits funds from an e-wallet to a designated client-owned account. RETURN: an automated transaction where a debit transaction was reversed and money moved back to originating account. RECALL: a transaction where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment. Possible values: BANK\_TRANSFER, PAYOUT, PIS\_PAY\_IN, REFUND, FUNDS\_SWEEP, RETURN, RECALL

**transactions->scheme** (nullable, string)  
The payment scheme used to execute this transaction. This is present only for transaction types PAYOUT and REFUND. FASTER\_PAYMENTS: The standard payment scheme within the UK. SEPA\_CREDIT\_TRANSFER: The standard payment to a beneficiary within the SEPA area. SEPA\_CREDIT\_TRANSFER\_INSTANT: Instant payment to a beneficiary within the SEPA area. Possible values: null, FASTER\_PAYMENTS, SEPA\_CREDIT\_TRANSFER, SEPA\_CREDIT\_TRANSFER\_INSTANT

**transactions->amount** (object)  
The amount and currency of a transaction

**transactions->amount->iso\_currency\_code** (string)  
An ISO-4217 currency code, used with e-wallets and transactions. Possible values: GBP, EURMin length: 3 Max length: 3

**transactions->amount->value** (number)  
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23. Format: double Minimum: 0.01

**transactions->counterparty** (object)  
An object representing the e-wallet transaction's counterparty

**transactions->counterparty->name** (string)  
The name of the counterparty Min length: 1

**transactions->counterparty->numbers** (object)  
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.

**transactions->counterparty->numbers->bacs** (nullable, object)  
The account number and sort code of the counterparty's account

**transactions->counterparty->numbers->bacs->account** (string)  
The account number of the account. Maximum of 10 characters. Min length: 1 Max length: 10

**transactions->counterparty->numbers->bacs->sort\_code** (string)  
The 6-character sort code of the account. Min length: 6 Max length: 6

**transactions->counterparty->numbers->international** (nullable, object)  
International Bank Account Number for a Wallet Transaction

**transactions->counterparty->numbers->international->iban** (string)  
International Bank Account Number (IBAN). Min length: 15 Max length: 34

**transactions->counterparty->address** (nullable, object)  
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.

**transactions->counterparty->address->street** (\[string\])  
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: 1 Min length: 1

**transactions->counterparty->address->city** (string)  
The city where the recipient is located. Maximum of 35 characters. Min length: 1 Max length: 35

**transactions->counterparty->address->postal\_code** (string)  
The postal code where the recipient is located. Maximum of 16 characters. Min length: 1 Max length: 16

**transactions->counterparty->address->country** (string)  
The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: 2 Max length: 2

**transactions->counterparty->date\_of\_birth** (nullable, string)  
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format. Format: date

**transactions->status** (string)  
The status of the transaction. AUTHORISING: The transaction is being processed for validation and compliance. INITIATED: The transaction has been initiated and is currently being processed. EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. FAILED: The transaction failed to process successfully. This is a terminal status. BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED

**transactions->created\_at** (string)  
Timestamp when the transaction was created, in ISO 8601 format. Format: date-time

**transactions->last\_status\_update** (string)  
The date and time of the last time the status was updated, in IS0 8601 format Format: date-time

**transactions->payment\_id** (nullable, string)  
The payment id that this transaction is associated with, if any. This is present only for transaction types PIS\_PAY\_IN and REFUND.

**transactions->failure\_reason** (nullable, string)  
The error code of a failed transaction. Error codes include: EXTERNAL\_SYSTEM: The transaction was declined by an external system. EXPIRED: The transaction request has expired. CANCELLED: The transaction request was rescinded. INVALID: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. UNKNOWN: The transaction was unsuccessful, but the exact cause is unknown. Possible values: EXTERNAL\_SYSTEM, EXPIRED, CANCELLED, INVALID, UNKNOWN

**transactions->error** (nullable, 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.

**transactions->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**transactions->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**transactions->error->error\_code\_reason** (nullable, 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.

**transactions->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**transactions->error->display\_message** (nullable, 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.

**transactions->error->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.

**transactions->error->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.

**transactions->error->status** (nullable, 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.

**transactions->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**transactions->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**transactions->related\_transactions** (\[object\])  
A list of wallet transactions that this transaction is associated with, if any.

**transactions->related\_transactions->id** (string)  
The ID of the related transaction.

**transactions->related\_transactions->type** (string)  
The type of the transaction. Possible values: PAYOUT, RETURN, REFUND, FUNDS\_SWEEP

**next\_cursor** (string)  
The value that, when used as the optional cursor parameter to /wallet/transaction/list, will return the corresponding transaction as its first entry.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "next_cursor": "YWJjMTIzIT8kKiYoKSctPUB",
  "transactions": [
    {
      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
      "type": "PAYOUT",
      "reference": "Payout 99744",
      "amount": {
        "iso_currency_code": "GBP",
        "value": 123.12
      },
      "status": "EXECUTED",
      "created_at": "2020-12-02T21:14:54Z",
      "last_status_update": "2020-12-02T21:15:01Z",
      "counterparty": {
        "numbers": {
          "bacs": {
            "account": "31926819",
            "sort_code": "601613"
          }
        },
        "name": "John Smith"
      },
      "related_transactions": [
        {
          "id": "wallet-transaction-id-sandbox-2ba30780-d549-4335-b1fe-c2a938aa39d2",
          "type": "RETURN"
        }
      ]
    },
    {
      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
      "type": "PAYOUT",
      "reference": "Payout 99744",
      "amount": {
        "iso_currency_code": "EUR",
        "value": 456.78
      },
      "status": "EXECUTED",
      "created_at": "2020-12-02T21:14:54Z",
      "last_status_update": "2020-12-02T21:15:01Z",
      "counterparty": {
        "numbers": {
          "international": {
            "iban": "GB33BUKB20201555555555"
          }
        },
        "name": "John Smith"
      },
      "related_transactions": []
    }
  ],
  "request_id": "4zlKapIkTm8p5KM"
}
```

### Webhooks 

Updates are sent to indicate that the status of transaction has changed. All virtual account webhooks have a `webhook_type` of `WALLET`.

\=\*=\*=\*=

#### WALLET\_TRANSACTION\_STATUS\_UPDATE 

Fired when the status of a wallet transaction has changed.

#### Properties 

**webhook\_type** (string)  
WALLET

**webhook\_code** (string)  
WALLET\_TRANSACTION\_STATUS\_UPDATE

**transaction\_id** (string)  
The transaction\_id for the wallet transaction being updated

**payment\_id** (string)  
The payment\_id associated with the transaction. This will be present in case of REFUND and PIS\_PAY\_IN.

**wallet\_id** (string)  
The EMI (E-Money Institution) wallet that this payment is associated with. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.

**new\_status** (string)  
The status of the transaction. AUTHORISING: The transaction is being processed for validation and compliance. INITIATED: The transaction has been initiated and is currently being processed. EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. FAILED: The transaction failed to process successfully. This is a terminal status. BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED

**old\_status** (string)  
The status of the transaction. AUTHORISING: The transaction is being processed for validation and compliance. INITIATED: The transaction has been initiated and is currently being processed. EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. FAILED: The transaction failed to process successfully. This is a terminal status. BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED

**timestamp** (string)  
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z" Format: date-time

**error** (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->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**error->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->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**error->display\_message** (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.

**error->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.

**error->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.

**error->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.

**error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**error->suggested\_action** (string)  
Suggested steps for resolving the error

**environment** (string)  
The Plaid environment the webhook was sent from Possible values: sandbox, production

```json
{
  "webhook_type": "WALLET",
  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
  "transaction_id": "wallet-transaction-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
  "payment_id": "payment-id-production-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
  "new_status": "SETTLED",
  "old_status": "INITIATED",
  "timestamp": "2017-09-14T14:42:19.350Z",
  "environment": "production"
}
```

---


# API - Sandbox | Plaid Docs

Sandbox endpoints 
==================

#### API reference for Sandbox endpoints 

\=\*=\*=\*=

#### Introduction 

Plaid's Sandbox environment provides a number of endpoints that can be used to configure testing scenarios. These endpoints are unique to the Sandbox environment and cannot be used in Production. For more information on these endpoints, see [Sandbox](https://plaid.com/docs/sandbox/index.html.md) .

| In this section |  |
| --- | --- |
| [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Bypass the Link flow for creating an Item |
| [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | Bypass the Link flow for creating an Item for a processor partner |
| [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Trigger the `ITEM_LOGIN_REQUIRED` state for an Item |
| [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) | (Income and Check) Force Item(s) for a Sandbox user into an error state |
| [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) | Fire a specific webhook |
| [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | (Auth) Set a verification status for testing micro-deposits |
| [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) | (Transfer) Fire a specific webhook |
| [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) | (Transfer) Simulate a deposit sweep event |
| [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) | (Transfer) Simulate converting pending balance into available balance |
| [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) | (Transfer) Simulate a withdraw sweep event |
| [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) | (Transfer) Simulate a transfer event |
| [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) | (Transfer) Simulate a refund event |
| [/sandbox/transfer/sweep/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersweepsimulate) | (Transfer) Simulate a transfer sweep event |
| [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) | (Transfer) Create a test clock for testing recurring transfers |
| [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) | (Transfer) Advance the time on a test clock |
| [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) | (Transfer) Get details about a test clock |
| [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) | (Transfer) Get details about all test clocks |
| [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) | (Income) Fire a specific webhook |
| [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) | (Check) Simulate an update for Cash Flow Updates |
| [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) | (Payment Initiation) Simulate a payment |
| [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) | (Transactions) Create custom transactions for Items |

\=\*=\*=\*=

#### /sandbox/public\_token/create 

#### Create a test Item 

Use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint to create a valid `public_token` for an arbitrary institution ID, initial products, and test credentials. The created `public_token` maps to a new Sandbox Item. You can then call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token` and perform all API actions. [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) can also be used with the [user\_custom test username](https://plaid.com/docs/sandbox/user-custom/index.html.md) to generate a test account with custom data, or with Plaid's [pre-populated Sandbox test accounts](https://plaid.com/docs/sandbox/test-credentials/index.html.md) .

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

**institution\_id** (required, string)  
The ID of the institution the Item will be associated with

**initial\_products** (required, \[string\])  
The products to initially pull for the Item. May be any products that the specified institution\_id supports. This array may not be empty. Min items: 1 Possible values: assets, auth, identity, income\_verification, investments\_auth, investments, liabilities, payment\_initiation, signal, standing\_orders, statements, transactions, transfer

**options** (object)  
An optional set of options to be used when configuring the Item. If specified, must not be null.

**options->webhook** (string)  
Specify a webhook to associate with the new Item.

**options->override\_username** (string)  
Test username to use for the creation of the Sandbox Item. Default value is user\_good. Default: user\_good

**options->override\_password** (string)  
Test password to use for the creation of the Sandbox Item. Default value is pass\_good. Default: pass\_good

**options->transactions** (object)  
An optional set of parameters corresponding to transactions options.

**options->transactions->start\_date** (string)  
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: date

**options->transactions->end\_date** (string)  
The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: date

**options->statements** (object)  
An optional set of parameters corresponding to statements options.

**options->statements->start\_date** (required, string)  
The earliest date for which to fetch statements history. Dates should be formatted as YYYY-MM-DD. Format: date

**options->statements->end\_date** (required, string)  
The most recent date for which to fetch statements history. Dates should be formatted as YYYY-MM-DD. Format: date

**options->income\_verification** (object)  
A set of parameters for income verification options. This field is required if income\_verification is included in the initial\_products array.

**options->income\_verification->income\_source\_types** (\[string\])  
The types of source income data that users will be permitted to share. Options include bank and payroll. Currently you can only specify one of these options. Possible values: bank, payroll

**options->income\_verification->bank\_income** (object)  
Specifies options for Bank Income. This field is required if income\_verification is included in the initial\_products array and bank is specified in income\_source\_types.

**options->income\_verification->bank\_income->days\_requested** (integer)  
The number of days of data to request for the Bank Income product

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
const publicTokenRequest: SandboxPublicTokenCreateRequest = {
  institution_id: institutionID,
  initial_products: initialProducts,
};
try {
  const publicTokenResponse = await client.sandboxPublicTokenCreate(
    publicTokenRequest,
  );
  const publicToken = publicTokenResponse.data.public_token;
  // The generated public_token can now be exchanged
  // for an access_token
  const exchangeRequest: ItemPublicTokenExchangeRequest = {
    public_token: publicToken,
  };
  const exchangeTokenResponse = await client.itemPublicTokenExchange(
    exchangeRequest,
  );
  const accessToken = exchangeTokenResponse.data.access_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**public\_token** (string)  
A public token that can be exchanged for an access token using /item/public\_token/exchange

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /sandbox/processor\_token/create 

#### Create a test Item and processor token 

Use the [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) endpoint to create a valid `processor_token` for an arbitrary institution ID and test credentials. The created `processor_token` corresponds to a new Sandbox Item. You can then use this `processor_token` with the `/processor/` API endpoints in Sandbox. You can also use [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) with the [user\_custom test username](https://plaid.com/docs/sandbox/user-custom/index.html.md) to generate a test account with custom data.

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

**institution\_id** (required, string)  
The ID of the institution the Item will be associated with

**options** (object)  
An optional set of options to be used when configuring the Item. If specified, must not be null.

**options->override\_username** (string)  
Test username to use for the creation of the Sandbox Item. Default value is user\_good. Default: user\_good

**options->override\_password** (string)  
Test password to use for the creation of the Sandbox Item. Default value is pass\_good. Default: pass\_good

```javascript
const request: SandboxProcessorTokenCreateRequest = {
  institution_id: institutionID,
};
try {
  const response = await plaidClient.sandboxProcessorTokenCreate(request);
  const processorToken = response.data.processor_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**processor\_token** (string)  
A processor token that can be used to call the /processor/ endpoints.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "processor_token": "processor-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /sandbox/item/reset\_login 

#### Force a Sandbox Item into an error state 

`/sandbox/item/reset_login/` forces an Item into an `ITEM_LOGIN_REQUIRED` state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow in the Sandbox environment. After calling [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) , You can then use Plaid Link update mode to restore the Item to a good state. An `ITEM_LOGIN_REQUIRED` webhook will also be fired after a call to this endpoint, if one is associated with the Item.  
In the Sandbox, Items will transition to an `ITEM_LOGIN_REQUIRED` error state automatically after 30 days, even if this endpoint is not called.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

```javascript
const request: SandboxItemResetLoginRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.sandboxItemResetLogin(request);
  // create a public_token for the Item and use it to
  // initialize Link in update mode.
  const pt_request: itemPublicTokenCreateRequest = {
    access_token: accessToken,
  };
  const pt_response = await plaidClient.itemCreatePublicToken(pt_request);
  const publicToken = pt_response.public_token;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**reset\_login** (boolean)  
true if the call succeeded

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "reset_login": true,
  "request_id": "m8MDnv9okwxFNBV"
}
```

\=\*=\*=\*=

#### /sandbox/user/reset\_login 

#### Force item(s) for a Sandbox User into an error state 

`/sandbox/user/reset_login/` functions the same as [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) , but will modify Items related to a User. This endpoint forces each Item into an `ITEM_LOGIN_REQUIRED` state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow in the Sandbox environment. After calling [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) , You can then use Plaid Link update mode to restore Items associated with the User to a good state. An `ITEM_LOGIN_REQUIRED` webhook will also be fired after a call to this endpoint, if one is associated with the Item.  
In the Sandbox, Items will transition to an `ITEM_LOGIN_REQUIRED` error state automatically after 30 days, even if this endpoint is not called.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**item\_ids** (\[string\])  
An array of item\_ids associated with the User to be reset. If empty or null, this field will default to resetting all Items associated with the User.

```javascript
const request: SandboxUserResetLoginRequest = {
  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6']
};
try {
  const response = await plaidClient.sandboxUserResetLogin(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "reset_login": true,
  "request_id": "n7XQnv8ozwyFPBC"
}
```

\=\*=\*=\*=

#### /sandbox/item/fire\_webhook 

#### Fire a test webhook 

The [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) endpoint is used to test that code correctly handles webhooks. This endpoint can trigger the following webhooks:  
`DEFAULT_UPDATE`: Webhook to be fired for a given Sandbox Item simulating a default update event for the respective product as specified with the `webhook_type` in the request body. Valid Sandbox `DEFAULT_UPDATE` webhook types include: `AUTH`, `IDENTITY`, `TRANSACTIONS`, `INVESTMENTS_TRANSACTIONS`, `LIABILITIES`, `HOLDINGS`. If the Item does not support the product, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result.  
`NEW_ACCOUNTS_AVAILABLE`: Fired to indicate that a new account is available on the Item and you can launch update mode to request access to it.  
`SMS_MICRODEPOSITS_VERIFICATION`: Fired when a given same day micro-deposit item is verified via SMS verification.  
`LOGIN_REPAIRED`: Fired when an Item recovers from the `ITEM_LOGIN_REQUIRED` without the user going through update mode in your app.  
`PENDING_DISCONNECT`: Fired when an Item will stop working in the near future (e.g. due to a planned bank migration) and must be sent through update mode to continue working.  
`RECURRING_TRANSACTIONS_UPDATE`: Recurring Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Recurring Transactions, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result.  
`SYNC_UPDATES_AVAILABLE`: Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result.  
`PRODUCT_READY`: Assets webhook to be fired when a given asset report has been successfully generated. If the Item does not support Assets, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result.  
`ERROR`: Assets webhook to be fired when asset report generation has failed. If the Item does not support Assets, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result.  
`USER_PERMISSION_REVOKED`: Indicates an end user has revoked the permission that they previously granted to access an Item. May not always fire upon revocation, as some institutions’ consent portals do not trigger this webhook. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the account or Item.  
`USER_ACCOUNT_REVOKED`: Fired when an end user has revoked access to their account on the Data Provider's portal. This webhook is currently sent only for Chase and PNC Items, but may be sent in the future for other financial institutions. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the account or Item.  
Note that this endpoint is provided for developer ease-of-use and is not required for testing webhooks; webhooks will also fire in Sandbox under the same conditions that they would in Production (except for webhooks of type `TRANSFER`).

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**webhook\_type** (string)  
The webhook types that can be fired by this test endpoint. Possible values: AUTH, HOLDINGS, INVESTMENTS\_TRANSACTIONS, ITEM, LIABILITIES, TRANSACTIONS, ASSETS

**webhook\_code** (required, string)  
The webhook codes that can be fired by this test endpoint. Possible values: DEFAULT\_UPDATE, NEW\_ACCOUNTS\_AVAILABLE, SMS\_MICRODEPOSITS\_VERIFICATION, USER\_PERMISSION\_REVOKED, USER\_ACCOUNT\_REVOKED, PENDING\_DISCONNECT, RECURRING\_TRANSACTIONS\_UPDATE, LOGIN\_REPAIRED, SYNC\_UPDATES\_AVAILABLE, PRODUCT\_READY, ERROR

```javascript
// Fire a DEFAULT_UPDATE webhook for an Item
const request: SandboxItemFireWebhookRequest = {
  access_token: accessToken
  webhook_code: 'DEFAULT_UPDATE'
};
try {
  const response = await plaidClient.sandboxItemFireWebhook(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**webhook\_fired** (boolean)  
Value is true if the test webhook\_code was successfully fired.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "webhook_fired": true,
  "request_id": "1vwmF5TBQwiqfwP"
}
```

\=\*=\*=\*=

#### /sandbox/item/set\_verification\_status 

#### Set verification status for Sandbox account 

The [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) endpoint can be used to change the verification status of an Item in in the Sandbox in order to simulate the Automated Micro-deposit flow.  
For more information on testing Automated Micro-deposits in Sandbox, see [Auth full coverage testing](https://plaid.com/docs/auth/coverage/testing/index.html.md#) .

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**account\_id** (required, string)  
The account\_id of the account whose verification status is to be modified

**verification\_status** (required, string)  
The verification status to set the account to. Possible values: automatically\_verified, verification\_expired

```javascript
const request: SandboxItemSetVerificationStatusRequest = {
  access_token: accessToken,
  account_id: accountID,
  verification_status: 'automatically_verified',
};
try {
  const response = await plaidClient.sandboxItemSetVerificationStatus(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "1vwmF5TBQwiqfwP"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/fire\_webhook 

#### Manually fire a Transfer webhook 

Use the [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) endpoint to manually trigger a `TRANSFER_EVENTS_UPDATE` webhook in the Sandbox environment.

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

**webhook** (required, string)  
The URL to which the webhook should be sent.

```javascript
const request: SandboxTransferFireWebhookRequest = {
  webhook: 'https://www.example.com',
};
try {
  const response = await plaidClient.sandboxTransferFireWebhook(request);
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/simulate 

#### Simulate a transfer event in Sandbox 

Use the [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) endpoint to simulate a transfer event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) or [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) , no transactions will actually take place and funds will not move between accounts, even within the Sandbox.

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

**transfer\_id** (required, string)  
Plaid’s unique identifier for a transfer.

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. If provided, the event to be simulated is created at the virtual\_time on the provided test\_clock.

**event\_type** (required, string)  
The asynchronous event to be simulated. May be: posted, settled, failed, funds\_available, or returned. An error will be returned if the event type is incompatible with the current transfer status. Compatible status --> event type transitions include: pending --> failed pending --> posted posted --> returned posted --> settled settled --> funds\_available (only applicable to ACH debits.)

**failure\_reason** (object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**failure\_reason->failure\_code** (string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**failure\_reason->ach\_return\_code** (deprecated, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**webhook** (string)  
The webhook URL to which a TRANSFER\_EVENTS\_UPDATE webhook should be sent.

```javascript
const request: SandboxTransferSimulateRequest = {
  transfer_id,
  event_type: 'posted',
  failure_reason: failureReason,
};
try {
  const response = await plaidClient.sandboxTransferSimulate(request);
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/refund/simulate 

#### Simulate a refund event in Sandbox 

Use the [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) endpoint to simulate a refund event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) or [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) , no transactions will actually take place and funds will not move between accounts, even within the Sandbox.

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

**refund\_id** (required, string)  
Plaid’s unique identifier for a refund.

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. If provided, the event to be simulated is created at the virtual\_time on the provided test\_clock.

**event\_type** (required, string)  
The asynchronous event to be simulated. May be: refund.posted, refund.settled, refund.failed, or refund.returned. An error will be returned if the event type is incompatible with the current refund status. Compatible status --> event type transitions include: refund.pending --> refund.failed refund.pending --> refund.posted refund.posted --> refund.returned refund.posted --> refund.settled refund.posted events can only be simulated if the refunded transfer has been transitioned to settled. This mimics the ordering of events in Production.

**failure\_reason** (object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**failure\_reason->failure\_code** (string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**failure\_reason->ach\_return\_code** (deprecated, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

**webhook** (string)  
The webhook URL to which a TRANSFER\_EVENTS\_UPDATE webhook should be sent.

```javascript
const request: SandboxTransferRefundSimulateRequest = {
  refund_id: refundId,
  event_type: 'refund.posted',
};
try {
  const response = await plaidClient.sandboxTransferRefundSimulate(request);
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/sweep/simulate 

#### Simulate creating a sweep 

Use the [/sandbox/transfer/sweep/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersweepsimulate) endpoint to create a sweep and associated events in the Sandbox environment. Upon calling this endpoint, all transfers with a sweep status of `swept` will become `swept_settled`, all `posted` or `pending` transfers with a sweep status of `unswept` will become `swept`, and all `returned` transfers with a sweep status of `swept` will become `return_swept`.

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

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. If provided, the sweep to be simulated is created on the day of the virtual\_time on the test\_clock. If the date of virtual\_time is on weekend or a federal holiday, the next available banking day is used.

**webhook** (string)  
The webhook URL to which a TRANSFER\_EVENTS\_UPDATE webhook should be sent.

```javascript
try {
  const response = await plaidClient.sandboxTransferSweepSimulate({});
  const sweep = response.data.sweep;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**sweep** (nullable, object)  
A sweep returned from the /sandbox/transfer/sweep/simulate endpoint. Can be null if there are no transfers to include in a sweep.

**sweep->id** (string)  
Identifier of the sweep.

**sweep->funding\_account\_id** (string)  
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

**sweep->ledger\_id** (nullable, string)  
Plaid’s unique identifier for a Plaid Ledger Balance.

**sweep->created** (string)  
The datetime when the sweep occurred, in RFC 3339 format. Format: date-time

**sweep->amount** (string)  
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

**sweep->iso\_currency\_code** (string)  
The currency of the sweep, e.g. "USD".

**sweep->settled** (nullable, string)  
The date when the sweep settled, in the YYYY-MM-DD format. Format: date

**sweep->expected\_funds\_available\_date** (nullable, string)  
The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: date

**sweep->status** (nullable, string)  
The status of a sweep transfer "pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled. This is the terminal state of a successful credit sweep. "returned" - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. "funds\_available" - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. "failed" - The sweep has failed. This is the terminal state of a failed sweep. Possible values: pending, posted, settled, funds\_available, returned, failed, null

**sweep->trigger** (nullable, string)  
The trigger of the sweep "manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance\_threshold" - The sweep is created by balance threshold setting "automatic\_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: manual, incoming, balance\_threshold, automatic\_aggregate

**sweep->description** (string)  
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

**sweep->network\_trace\_id** (nullable, string)  
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For ach or same-day-ach transfers, this is the ACH trace number. For rtp transfers, this is the Transaction Identification number. For wire transfers, this is the IMAD (Input Message Accountability Data) number.

**sweep->failure\_reason** (nullable, object)  
The failure reason if the status for a sweep is "failed" or "returned". Null value otherwise.

**sweep->failure\_reason->failure\_code** (nullable, string)  
The failure code, e.g. R01. A failure code will be provided if and only if the sweep status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**sweep->failure\_reason->description** (nullable, string)  
A human-readable description of the reason for the failure or reversal.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "sweep": {
    "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "created": "2020-08-06T17:27:15Z",
    "amount": "12.34",
    "iso_currency_code": "USD",
    "settled": "2020-08-07",
    "network_trace_id": null
  },
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/ledger/deposit/simulate 

#### Simulate a ledger deposit event in Sandbox 

Use the [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) endpoint to simulate a ledger deposit event in the Sandbox environment.

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

**sweep\_id** (required, string)  
Plaid’s unique identifier for a sweep.

**event\_type** (required, string)  
The asynchronous event to be simulated. May be: posted, settled, failed, or returned. An error will be returned if the event type is incompatible with the current ledger sweep status. Compatible status --> event type transitions include: sweep.pending --> sweep.posted sweep.pending --> sweep.failed sweep.posted --> sweep.settled sweep.posted --> sweep.returned sweep.settled --> sweep.returned Possible values: sweep.posted, sweep.settled, sweep.returned, sweep.failed

**failure\_reason** (object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**failure\_reason->failure\_code** (string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**failure\_reason->ach\_return\_code** (deprecated, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

```javascript
const request: SandboxTransferLedgerDepositSimulateRequest = {
  sweep_id: 'f4ba7a287eae4d228d12331b68a9f35a',
  event_type: 'sweep.posted',
};
try {
  const response = await plaidClient.sandboxTransferLedgerDepositSimulate(
    request,
  );
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/ledger/simulate\_available 

#### Simulate converting pending balance to available balance 

Use the [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) endpoint to simulate converting pending balance to available balance for all originators in the Sandbox environment.

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

**ledger\_id** (string)  
Specify which ledger balance to simulate converting pending balance to available balance. If this field is left blank, this will default to id of the default ledger balance.

**originator\_client\_id** (string)  
Client ID of the end customer (i.e. the originator). Only applicable to Platform Payments customers.

**test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. If provided, only the pending balance that is due before the virtual\_timestamp on the test clock will be converted.

**webhook** (string)  
The webhook URL to which a TRANSFER\_EVENTS\_UPDATE webhook should be sent.

```javascript
try {
  const response = await plaidClient.sandboxTransferLedgerSimulateAvailable({});
  const available = response.data.balance.available;
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/ledger/withdraw/simulate 

#### Simulate a ledger withdraw event in Sandbox 

Use the [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) endpoint to simulate a ledger withdraw event in the Sandbox environment.

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

**sweep\_id** (required, string)  
Plaid’s unique identifier for a sweep.

**event\_type** (required, string)  
The asynchronous event to be simulated. May be: posted, settled, failed, or returned. An error will be returned if the event type is incompatible with the current ledger sweep status. Compatible status --> event type transitions include: sweep.pending --> sweep.posted sweep.pending --> sweep.failed sweep.posted --> sweep.settled sweep.posted --> sweep.returned sweep.settled --> sweep.returned Possible values: sweep.posted, sweep.settled, sweep.returned, sweep.failed

**failure\_reason** (object)  
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

**failure\_reason->failure\_code** (string)  
The failure code, e.g. R01. A failure code will be provided if and only if the transfer status is returned. See ACH return codes for a full listing of ACH return codes and RTP/RfP error codes for RTP error codes.

**failure\_reason->ach\_return\_code** (deprecated, string)  
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

**failure\_reason->description** (string)  
A human-readable description of the reason for the failure or reversal.

```javascript
const request: SandboxTransferLedgerWithdrawSimulateRequest = {
  sweep_id: 'f4ba7a287eae4d228d12331b68a9f35a',
  event_type: 'sweep.posted',
};
try {
  const response = await plaidClient.sandboxTransferLedgerWithdrawSimulate(
    request,
  );
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/test\_clock/create 

#### Create a test clock 

Use the [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) endpoint to create a `test_clock` in the Sandbox environment.  
A test clock object represents an independent timeline and has a `virtual_time` field indicating the current timestamp of the timeline. Test clocks are used for testing recurring transfers in Sandbox.  
A test clock can be associated with up to 5 recurring transfers.

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

**virtual\_time** (string)  
The virtual timestamp on the test clock. If not provided, the current timestamp will be used. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

```javascript
const request: SandboxTransferTestClockCreateRequest = {
  virtual_time: '2006-01-02T15:04:05Z',
};
try {
  const response = await plaidClient.sandboxTransferTestClockCreate(request);
  const test_clock = response.data.test_clock;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**test\_clock** (object)  
Defines the test clock for a transfer.

**test\_clock->test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a test\_clock\_id was included in the /transfer/recurring/create request. For more details, see Simulating recurring transfers.

**test\_clock->virtual\_time** (string)  
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "test_clock": {
    "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
    "virtual_time": "2006-01-02T15:04:05Z"
  },
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/test\_clock/advance 

#### Advance a test clock 

Use the [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) endpoint to advance a `test_clock` in the Sandbox environment.  
A test clock object represents an independent timeline and has a `virtual_time` field indicating the current timestamp of the timeline. A test clock can be advanced by incrementing `virtual_time`, but may never go back to a lower `virtual_time`.  
If a test clock is advanced, we will simulate the changes that ought to occur during the time that elapsed.  
For example, a client creates a weekly recurring transfer with a test clock set at t. When the client advances the test clock by setting `virtual_time` = t + 15 days, 2 new originations should be created, along with the webhook events.  
The advancement of the test clock from its current `virtual_time` should be limited such that there are no more than 20 originations resulting from the advance operation on each `recurring_transfer` associated with the `test_clock`.  
For example, if the recurring transfer associated with this test clock originates once every 4 weeks, you can advance the `virtual_time` up to 80 weeks on each API call.

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

**test\_clock\_id** (required, string)  
Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a test\_clock\_id was included in the /transfer/recurring/create request. For more details, see Simulating recurring transfers.

**new\_virtual\_time** (required, string)  
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

```javascript
const request: SandboxTransferTestClockAdvanceRequest = {
  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c',
  new_virtual_time: '2006-01-02T15:04:05Z',
};
try {
  const response = await plaidClient.sandboxTransferTestClockAdvance(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/test\_clock/get 

#### Get a test clock 

Use the [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) endpoint to get a `test_clock` in the Sandbox environment.

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

**test\_clock\_id** (required, string)  
Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a test\_clock\_id was included in the /transfer/recurring/create request. For more details, see Simulating recurring transfers.

```javascript
const request: SandboxTransferTestClockGetRequest = {
  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c',
};
try {
  const response = await plaidClient.sandboxTransferTestClockGet(request);
  const test_clock = response.data.test_clock;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**test\_clock** (object)  
Defines the test clock for a transfer.

**test\_clock->test\_clock\_id** (string)  
Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a test\_clock\_id was included in the /transfer/recurring/create request. For more details, see Simulating recurring transfers.

**test\_clock->virtual\_time** (string)  
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "test_clock": {
    "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
    "virtual_time": "2006-01-02T15:04:05Z"
  },
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/transfer/test\_clock/list 

#### List test clocks 

Use the [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) endpoint to see a list of all your test clocks in the Sandbox environment, by ascending `virtual_time`. Results are paginated; use the `count` and `offset` query parameters to retrieve the desired test clocks.

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

**start\_virtual\_time** (string)  
The start virtual timestamp of test clocks to return. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**end\_virtual\_time** (string)  
The end virtual timestamp of test clocks to return. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: date-time

**count** (integer)  
The maximum number of test clocks to return. Minimum: 1 Maximum: 25 Default: 25

**offset** (integer)  
The number of test clocks to skip before returning results. Default: 0 Minimum: 0

```javascript
const request: SandboxTransferTestClockListRequest = {
  count: 2,
};
try {
  const response = await plaidClient.sandboxTransferTestClockList(request);
  const test_clocks = response.data.test_clocks;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**test\_clocks** (\[object\])  
Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a test\_clock\_id was included in the /transfer/recurring/create request. For more details, see Simulating recurring transfers.

**test\_clocks->virtual\_time** (string)  
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z. Format: date-time

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "test_clocks": [
    {
      "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
      "virtual_time": "2006-01-02T15:04:05Z"
    },
    {
      "test_clock_id": "a33a6eda-5e97-5d64-244a-a9274110152d",
      "virtual_time": "2006-02-02T15:04:05Z"
    }
  ],
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/income/fire\_webhook 

#### Manually fire an Income webhook 

Use the [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) endpoint to manually trigger a Payroll or Document Income webhook in the Sandbox environment.

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

**item\_id** (required, string)  
The Item ID associated with the verification.

**user\_id** (string)  
The Plaid user\_id of the User associated with this webhook, warning, or error.

**webhook** (required, string)  
The URL to which the webhook should be sent.

**verification\_status** (string)  
VERIFICATION\_STATUS\_PROCESSING\_COMPLETE: The income verification status processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /income/verification/paystubs/get endpoint and check the document metadata to see which documents were successfully parsed. VERIFICATION\_STATUS\_PROCESSING\_FAILED: A failure occurred when attempting to process the verification documentation. VERIFICATION\_STATUS\_PENDING\_APPROVAL: (deprecated) The income verification has been sent to the user for review. Possible values: VERIFICATION\_STATUS\_PROCESSING\_COMPLETE, VERIFICATION\_STATUS\_PROCESSING\_FAILED, VERIFICATION\_STATUS\_PENDING\_APPROVAL

**webhook\_code** (required, string)  
The webhook codes that can be fired by this test endpoint. Possible values: INCOME\_VERIFICATION, INCOME\_VERIFICATION\_RISK\_SIGNALS

```javascript
const request: SandboxIncomeFireWebhookRequest = {
  item_id: 'Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM',
  webhook: 'https://webhook.com/',
  verification_status: 'VERIFICATION_STATUS_PROCESSING_COMPLETE',
};
try {
  const response = await plaidClient.sandboxIncomeFireWebhook(request);
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/cra/cashflow\_updates/update 

#### Trigger an update for Cash Flow Updates 

Use the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) endpoint to manually trigger an update for Cash Flow Updates (Monitoring) in the Sandbox environment.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**webhook\_codes** (\[string\])  
Webhook codes corresponding to the Cash Flow Updates events to be simulated. Possible values: LARGE\_DEPOSIT\_DETECTED, LOW\_BALANCE\_DETECTED, NEW\_LOAN\_PAYMENT\_DETECTED, NSF\_OVERDRAFT\_DETECTED

```javascript
const request: SandboxCraCashflowUpdatesUpdateRequest = {
  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  webhook_codes: ['LARGE_DEPOSIT_DETECTED', 'LOW_BALANCE_DETECTED'],
};
try {
  const response = await plaidClient.sandbox_cra_cashflow_updates_update(request);
  // empty response upon success
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "mdqfuVxeoza6mhu"
}
```

\=\*=\*=\*=

#### /sandbox/payment/simulate 

#### Simulate a payment event in Sandbox 

Use the [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) endpoint to simulate various payment events in the Sandbox environment. This endpoint will trigger the corresponding payment status webhook.

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

**payment\_id** (required, string)  
The ID of the payment to simulate

**webhook** (required, string)  
The webhook url to use for any payment events triggered by the simulated status change.

**status** (required, string)  
The status to set the payment to. Valid statuses include:PAYMENT\_STATUS\_INITIATEDPAYMENT\_STATUS\_INSUFFICIENT\_FUNDSPAYMENT\_STATUS\_FAILEDPAYMENT\_STATUS\_EXECUTEDPAYMENT\_STATUS\_SETTLEDPAYMENT\_STATUS\_CANCELLEDPAYMENT\_STATUS\_REJECTED

```javascript
const request: SandboxPaymentSimulateRequest = {
  payment_id: 'payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3',
  status: "PAYMENT_STATUS_INITIATED"
};
try {
  const response = await plaidClient.sandbox_payment_simulate(request);
} catch (error) {
  // handle error
}
```

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

**old\_status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

**new\_status** (string)  
The status of the payment. Core lifecycle statuses: PAYMENT\_STATUS\_INPUT\_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT\_STATUS\_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT\_STATUS\_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT\_STATUS\_EXECUTED state or the funds settle in the recipient account. PAYMENT\_STATUS\_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT\_STATUS\_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT\_STATUS\_EXECUTED is not terminal—the payment will continue to PAYMENT\_STATUS\_SETTLED once funds are available. PAYMENT\_STATUS\_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT\_STATUS\_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT\_STATUS\_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT\_STATUS\_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT\_STATUS\_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT\_STATUS\_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT\_STATUS\_UNKNOWN: The payment status is unknown. PAYMENT\_STATUS\_PROCESSING: The payment is currently being processed. PAYMENT\_STATUS\_COMPLETED: Indicates that the standing order has been successfully established. Possible values: PAYMENT\_STATUS\_INPUT\_NEEDED, PAYMENT\_STATUS\_PROCESSING, PAYMENT\_STATUS\_INITIATED, PAYMENT\_STATUS\_COMPLETED, PAYMENT\_STATUS\_INSUFFICIENT\_FUNDS, PAYMENT\_STATUS\_FAILED, PAYMENT\_STATUS\_BLOCKED, PAYMENT\_STATUS\_UNKNOWN, PAYMENT\_STATUS\_EXECUTED, PAYMENT\_STATUS\_SETTLED, PAYMENT\_STATUS\_AUTHORISING, PAYMENT\_STATUS\_CANCELLED, PAYMENT\_STATUS\_ESTABLISHED, PAYMENT\_STATUS\_REJECTED

```json
{
  "request_id": "m8MDnv9okwxFNBV",
  "old_status": "PAYMENT_STATUS_INPUT_NEEDED",
  "new_status": "PAYMENT_STATUS_INITIATED"
}
```

\=\*=\*=\*=

#### /sandbox/transactions/create 

#### Create sandbox transactions 

Use the [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) endpoint to create new transactions for an existing Item. This endpoint can be used to add up to 10 transactions to any Item at a time.  
This endpoint can only be used with Items that were created in the Sandbox environment using the `user_transactions_dynamic` test user. You can use this to add transactions to test the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) and [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoints.

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

**access\_token** (required, string)  
The access token associated with the Item data is being requested for.

**transactions** (required, \[object\])  
List of transactions to be added

**transactions->date\_transacted** (required, string)  
The date of the transaction, in ISO 8601 (YYYY-MM-DD) format. Transaction date must be the present date or a date up to 14 days in the past. Future dates are not allowed. Format: date

**transactions->date\_posted** (required, string)  
The date the transaction posted, in ISO 8601 (YYYY-MM-DD) format. Posted date must be the present date or a date up to 14 days in the past. Future dates are not allowed. Format: date

**transactions->amount** (required, number)  
The transaction amount. Can be negative. Format: double

**transactions->description** (required, string)  
The transaction description.

**transactions->iso\_currency\_code** (string)  
The ISO-4217 format currency code for the transaction. Defaults to USD.

```javascript
const request: SandboxTransactionsCreateRequest = {
  access_token: accessToken,
  transactions: [
    {
      amount: 100.50,
      date_posted: '2025-06-08',
      date_transacted: '2025-06-08',
      description: 'Tim Hortons'
    },
    {
      amount: -25.75,
      date_posted: '2025-06-08',
      date_transacted: '2025-06-08',
      description: 'BestBuy',
      iso_currency_code: 'CAD'
    }
  ]
};
try {
  const response = await plaidClient.sandbox_transactions_create(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "m8MDnv9okwxFNBV"
}
```

---


# API - Users | Plaid Docs

User endpoints 
===============

#### API reference for User tokens 

This page covers API endpoints related to user tokens, which are used by [Plaid Check](https://plaid.com/docs/check/index.html.md) and [Income](https://plaid.com/docs/income/index.html.md) , as well as by the [Multi-Item Link flow](https://plaid.com/docs/link/multi-item-link/index.html.md) .

| Endpoints |  |
| --- | --- |
| [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | Create a user ID and token |
| [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) | Update user data or enable an existing user token for Plaid Check |
| [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) | Remove the user and their associated Items |
| [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) | Return Items associated with a user |

| See also |  |
| --- | --- |
| [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) | Force user into an error state for testing |

\=\*=\*=\*=

#### /user/create 

#### Create user 

This endpoint should be called for each of your end users before they begin a Plaid Check or Income flow, or a Multi-Item Link flow. This provides you a single token to access all data associated with the user. You should only create one per end user.  
The `consumer_report_user_identity` object must be present in order to create a Plaid Check Consumer Report for a user. If it is not provided during the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) call, it can be added later by calling [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) . Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`.  
If you call the endpoint multiple times with the same `client_user_id`, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given `client_user_id`.  
Ensure that you store the `user_token` along with your user's identifier in your database, as it is not possible to retrieve a previously created `user_token`.

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

**client\_user\_id** (required, string)  
A unique ID representing the end user. Maximum of 128 characters. 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. Max length: 128 Min length: 1

**consumer\_report\_user\_identity** (object)  
To create a Plaid Check Consumer Report for a user, this field must be present on the user token. If this field is not provided during user token creation, you can add it to the user later by calling /user/update. Once the field has been added to the user, you will be able to call /link/token/create with a non-empty consumer\_report\_permissible\_purpose (which will automatically create a Plaid Check Consumer Report), or call /cra/check\_report/create for that user.

**consumer\_report\_user\_identity->first\_name** (required, string)  
The user's first name

**consumer\_report\_user\_identity->last\_name** (required, string)  
The user's last name

**consumer\_report\_user\_identity->phone\_numbers** (required, \[string\])  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**consumer\_report\_user\_identity->emails** (required, \[string\])  
The user's emails

**consumer\_report\_user\_identity->ssn\_last\_4** (string)  
The last 4 digits of the user's social security number. Max length: 4 Min length: 4

**consumer\_report\_user\_identity->date\_of\_birth** (required, string)  
To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers. Format: date

**consumer\_report\_user\_identity->primary\_address** (required, object)  
Data about the components comprising an address.

**consumer\_report\_user\_identity->primary\_address->city** (required, string)  
The full city name

**consumer\_report\_user\_identity->primary\_address->region** (required, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**consumer\_report\_user\_identity->primary\_address->street** (required, string)  
The full street address Example: "564 Main Street, APT 15"

**consumer\_report\_user\_identity->primary\_address->postal\_code** (required, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**consumer\_report\_user\_identity->primary\_address->country** (required, string)  
The ISO 3166-1 alpha-2 country code

```javascript
const request = {
  client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d',
  consumer_report_user_identity: {
    first_name: "Carmen",
    last_name: "Berzatto",
    phone_numbers: ["+13125551212"],
    emails: ["carmy@example.com", "bear@example.com"],
    ssn_last_4: "1234",
    date_of_birth: "1987-01-31",
    primary_address: {
      city: "Chicago",
      region: "IL",
      street: "3200 W Armitage Ave",
      postal_code: "60657",
      country: "US"      
    }
  }
};


try {
  const response = await client.userCreate(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**user\_token** (string)  
The user token associated with the User data is being requested for.

**user\_id** (string)  
The Plaid user\_id of the User associated with this webhook, warning, or error.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /user/update 

#### Update user information 

This endpoint is used to update user information associated with an existing `user_token`. It can also be used to enable an existing `user_token` for use with Consumer Reports by Plaid Check, by adding a `consumer_report_user_identity` object to the user. Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

**consumer\_report\_user\_identity** (required, object)  
To create a Plaid Check Consumer Report for a user, this field must be present on the user token. If this field is not provided during user token creation, you can add it to the user later by calling /user/update. Once the field has been added to the user, you will be able to call /link/token/create with a non-empty consumer\_report\_permissible\_purpose (which will automatically create a Plaid Check Consumer Report), or call /cra/check\_report/create for that user.

**consumer\_report\_user\_identity->first\_name** (required, string)  
The user's first name

**consumer\_report\_user\_identity->last\_name** (required, string)  
The user's last name

**consumer\_report\_user\_identity->phone\_numbers** (required, \[string\])  
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.

**consumer\_report\_user\_identity->emails** (required, \[string\])  
The user's emails

**consumer\_report\_user\_identity->ssn\_last\_4** (string)  
The last 4 digits of the user's social security number. Max length: 4 Min length: 4

**consumer\_report\_user\_identity->date\_of\_birth** (required, string)  
To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers. Format: date

**consumer\_report\_user\_identity->primary\_address** (required, object)  
Data about the components comprising an address.

**consumer\_report\_user\_identity->primary\_address->city** (required, string)  
The full city name

**consumer\_report\_user\_identity->primary\_address->region** (required, string)  
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

**consumer\_report\_user\_identity->primary\_address->street** (required, string)  
The full street address Example: "564 Main Street, APT 15"

**consumer\_report\_user\_identity->primary\_address->postal\_code** (required, string)  
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

**consumer\_report\_user\_identity->primary\_address->country** (required, string)  
The ISO 3166-1 alpha-2 country code

```javascript
const request = {
  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
  consumer_report_user_identity: {
    first_name: "Carmen",
    last_name: "Berzatto",
    phone_numbers: ["+13125551212"],
    emails: ["carmy@example.com", "bear@example.com"],
    ssn_last_4: "1234",
    date_of_birth: "1987-01-31",
    primary_address: {
      city: "Chicago",
      region: "IL",
      street: "3200 W Armitage Ave",
      postal_code: "60657",
      country: "US"      
    }
  }
};


try {
  const response = await client.userUpdate(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /user/remove 

#### Remove user 

[/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) deletes a user token and and associated information, including any Items associated with the token. Any subsequent calls to retrieve information using the same user token will result in an error stating the user does not exist. If a user is created for a given `client_user_id` using [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and that user is then deleted with [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) , the `client_user_id` cannot be reused for another [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) request.

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

**user\_token** (string)  
The user token associated with the User data is being requested for.

```javascript
const request = {
  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab'
};


try {
  const response = await client.userRemove(request);
} catch (error) {
  // handle error
}
```

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

```json
{
  "request_id": "Aim3b"
}
```

\=\*=\*=\*=

#### /user/items/get 

#### Get Items associated with a User 

Returns Items associated with a User along with their corresponding statuses.

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

**user\_token** (required, string)  
The user token associated with the User data is being requested for.

```javascript
const request = {
  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab'
};


try {
  const response = await client.userItemsGetRequest(request);
} catch (error) {
  // handle error
}
```

#### Response fields and example 

string

**items** (\[object\])  
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.

**items->institution\_id** (nullable, string)  
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**items->institution\_name** (nullable, string)  
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.

**items->webhook** (nullable, string)  
The URL registered to receive webhooks for the Item.

**items->auth\_method** (nullable, string)  
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation. INSTANT\_AUTH: The Item's Auth data was provided directly by the user's institution connection. INSTANT\_MATCH: The Item's Auth data was provided via the Instant Match fallback flow. AUTOMATED\_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow. SAME\_DAY\_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow. INSTANT\_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow. DATABASE\_MATCH: The Item's Auth data was provided via the Database Match flow. DATABASE\_INSIGHTS: The Item's Auth data was provided via the Database Insights flow. TRANSFER\_MIGRATED: The Item's Auth data was provided via /transfer/migrate\_account. INVESTMENTS\_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow. Possible values: INSTANT\_AUTH, INSTANT\_MATCH, AUTOMATED\_MICRODEPOSITS, SAME\_DAY\_MICRODEPOSITS, INSTANT\_MICRODEPOSITS, DATABASE\_MATCH, DATABASE\_INSIGHTS, TRANSFER\_MIGRATED, INVESTMENTS\_FALLBACK, null

**items->error** (nullable, 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.

**items->error->error\_type** (string)  
A broad categorization of the error. Safe for programmatic use. Possible values: INVALID\_REQUEST, INVALID\_RESULT, INVALID\_INPUT, INSTITUTION\_ERROR, RATE\_LIMIT\_EXCEEDED, API\_ERROR, ITEM\_ERROR, ASSET\_REPORT\_ERROR, RECAPTCHA\_ERROR, OAUTH\_ERROR, PAYMENT\_ERROR, BANK\_TRANSFER\_ERROR, INCOME\_VERIFICATION\_ERROR, MICRODEPOSITS\_ERROR, SANDBOX\_ERROR, PARTNER\_ERROR, TRANSACTIONS\_ERROR, TRANSACTION\_ERROR, TRANSFER\_ERROR, CHECK\_REPORT\_ERROR, CONSUMER\_REPORT\_ERROR

**items->error->error\_code** (string)  
The particular error code. Safe for programmatic use.

**items->error->error\_code\_reason** (nullable, 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.

**items->error->error\_message** (string)  
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

**items->error->display\_message** (nullable, 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.

**items->error->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.

**items->error->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.

**items->error->status** (nullable, 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.

**items->error->documentation\_url** (string)  
The URL of a Plaid documentation page with more information about the error

**items->error->suggested\_action** (nullable, string)  
Suggested steps for resolving the error

**items->available\_products** (\[string\])  
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**items->billed\_products** (\[string\])  
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available\_products. Note - billed\_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**items->products** (\[string\])  
A list of products added to the Item. In almost all cases, this will be the same as the billed\_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset\_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed\_products. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, payment\_initiation, identity\_verification, transactions, credit\_details, income, income\_verification, standing\_orders, transfer, employment, recurring\_transactions, transactions\_refresh, signal, statements, processor\_payments, processor\_identity, profile, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_network\_insights, cra\_cashflow\_insights, cra\_monitoring, layer, pay\_by\_bank, protect\_linked\_bank

**items->consented\_products** (\[string\])  
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: assets, auth, balance, balance\_plus, beacon, identity, identity\_match, investments, investments\_auth, liabilities, transactions, income, income\_verification, transfer, employment, recurring\_transactions, signal, statements, processor\_payments, processor\_identity, cra\_base\_report, cra\_income\_insights, cra\_partner\_insights, cra\_cashflow\_insights, cra\_monitoring, layer

**items->consent\_expiration\_time** (nullable, string)  
The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide. Format: date-time

**items->update\_type** (string)  
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. background - Item can be updated in the background user\_present\_required - Item requires user interaction to be updated Possible values: background, user\_present\_required

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "items": [
    {
      "available_products": [
        "balance",
        "auth"
      ],
      "billed_products": [
        "identity",
        "transactions"
      ],
      "error": null,
      "institution_id": "ins_109508",
      "institution_name": "First Platypus Bank",
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "update_type": "background",
      "webhook": "https://plaid.com/example/hook",
      "consent_expiration_time": null
    },
    {
      "available_products": [
        "balance",
        "identity",
        "payment_initiation",
        "transactions"
      ],
      "billed_products": [
        "assets",
        "auth"
      ],
      "error": null,
      "institution_id": "ins_109508",
      "institution_name": "First Platypus Bank",
      "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
      "update_type": "background",
      "webhook": "https://plaid.com/example/hook",
      "consent_expiration_time": null
    }
  ],
  "request_id": "m8MDnv9okwxFNBV"
}
```

---


# API - API versioning | Plaid Docs

API versioning and changelog 
=============================

#### Keep track of changes and updates to the Plaid API 

\=\*=\*=\*=

#### API versioning 

This page covers backwards-incompatible, versioned API changes. For a list of all API updates, including non-versioned ones, see the [changelog](https://plaid.com/docs/changelog/index.html.md) .

Whenever we make a backwards-incompatible change to a general availability, non-beta product, we release a new API version to avoid causing breakages for existing developers. You can then continue to use the old API version, or update your application to upgrade to the new Plaid API version. APIs for beta products are subject to breaking changes without versioning, with 30 days notice.

We consider the following changes to be backwards compatible (non-breaking):

*   Adding new API endpoints
*   Adding new optional parameters to existing endpoints
*   Adding new data elements to existing response schemas or webhooks
*   Adding new enum values, including `error_types` and `error_codes`
*   Subdividing existing `error_codes` into more precise errors, and changing the http response code as necessary, as long as the error cannot be resolved via in-app logic (such as launching update mode or waiting for a few seconds and retrying) during runtime. For example, changing `PRODUCT_NOT_READY` errors to a different `error_code` would be a breaking change, since that error can be resolved by retrying a few seconds later, but converting an existing `INTERNAL_SERVER_ERROR` to a more specific error would not be.
*   Changing the behavior for use cases or platforms that are explicitly not supported.
*   Adding new `webhook_types` and `webhook_codes`
*   Changing the length or content of any API identifier

##### How to set your API version 

The default version of the API used in any requests you make can be configured in the [Dashboard](https://dashboard.plaid.com/developers/api) and will be used when version information is not otherwise specified. You can also manually set the `Plaid-Version` header to use a specific version for a given API request.

If you're using one of the Plaid client libraries, they should all be pinned to the latest version of the API at the time when they were released. This means that you can change the API version you're using by updating to a newer version of the client library.

```javascript
const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const client = new PlaidApi(configuration);
```

\=\*=\*=\*=

#### Version 2020-09-14 

This version includes several changes to improve authentication, streamline and simplify the API, and improve international support.

*   To improve authentication, the `public_key` has been fully removed from the API. Endpoints that previously accepted a `public_key` for authentication, namely [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) and [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) , now require a `client_id` and `secret` for authentication instead.
    
*   [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) no longer returns a `removed` boolean. This field created developer confusion, because it was never possible for it to return `false`. A failed [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) call will result in an [error](https://plaid.com/docs/errors/index.html.md) being returned instead.
    
*   Several undocumented and unused fields have been removed from the `institution` object returned by the institutions endpoints [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) , [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) , and [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) . The removed fields are: `input_spec`, `credentials`, `include_display_data`, `has_mfa`, `mfa`, and `mfa_code_type`.
    
*   The institutions endpoints [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) , [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) , and [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) now require the use of a `country_codes` parameter and no longer use `US` as a default value if `country_codes` is not specified, as this behavior caused confusion and unexpected behavior for non-US developers. As part of this change, the `country_codes` parameter has been moved out of the `options` object and is now a top-level parameter.
    
*   To support international payments, the response schema for the partner-only [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) endpoint has changed. The 2018-05-22 and 2019-05-29 API releases previously extended the response schema for [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) in order to support international accounts, but these changes were never extended to the [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) endpoint. This release brings the response for [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) in line with the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) response, allowing Plaid partners to extend support for using non-ACH payment methods, such as EFT payments (Canada) or SEPA credit and direct debit (Europe). Accommodating this change does not require any code changes from Plaid developers who use partnership integrations, only from the Plaid partners themselves.
    

```json
"numbers": [{
  "account": "9900009606",
  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
  "routing": "011401533",
  "wire_routing": "021000021"
}]
```

```json
"numbers": {
  "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
  }],
  "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "021",
    "branch": "01140"
  }],
  "international":[{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "bic": "NWBKGB21"
    "iban": "GB29NWBK60161331926819",
  }],
  "bacs":[{
    "account": "31926819",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "sort_code": "601613"
  }]
}
```

\=\*=\*=\*=

#### Version 2019-05-29 

*   The Auth `numbers` schema has been extended to support BACS (UK) and other international (IBAN and BIC) account numbers used across the EU.
*   Renamed the `zip` field to `postal_code` and the `state` field to `region` in all [Identity](https://plaid.com/docs/api/products/identity/index.html.md) and [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) responses to be more international friendly.
*   [Identity](https://plaid.com/docs/api/products/identity/index.html.md) objects in [Identity responses](https://plaid.com/docs/api/products/identity/index.html.md) are now embedded on the `owners` field of the corresponding account.
*   Address data fields for [Identity](https://plaid.com/docs/api/products/identity/index.html.md) responses are now nullable and are returned with a null value when they aren’t available rather than an empty string.
*   Added a ISO-3166-1 alpha-2 `country` field to all [Identity](https://plaid.com/docs/api/products/identity/index.html.md) and [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) responses.
*   The account type `brokerage` has been renamed to `investment`.

These changes are meant to enable access to International institutions for Plaid’s launch in Europe and add support for investment accounts. Test in the [Sandbox](https://plaid.com/docs/sandbox/index.html.md) with the new API version to see the new Schema and enable support for International institutions from the [Dashboard](https://dashboard.plaid.com/developers/api) in order to create Items for these institutions.

##### Auth 

Before, `numbers` only had fields for `ach` (US accounts) and `eft` (Canadian accounts) accounts numbers:

```json
"numbers": {
  "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
  }],
  "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "021",
    "branch": "01140"
  }]
}
```

Now, the structure of `numbers` hasn’t changed, but it can have `ach`, `eft`, `bacs` (UK accounts), or `international` (currently EU accounts) numbers. Note that the schema for each of these numbers are different from one another. It is possible for multiple networks to be present in the response.

```json
"numbers": {
  "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
  }],
  "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "021",
    "branch": "01140"
  }],
  "international":[{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "bic": "NWBKGB21"
    "iban": "GB29NWBK60161331926819",
  }],
  "bacs":[{
    "account": "31926819",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "sort_code": "601613"
  }]
}
```

##### Identity 

The previous version of [Identity](https://plaid.com/docs/api/products/identity/index.html.md) had US specific field names and did not include a country as part of the location. Furthermore, the identity data was not scoped to a specific account.

```json
"identity": {
  "addresses": [{
    "accounts": [
      "Plaid Checking 0000",
      "Plaid Saving 1111",
      "Plaid CD 2222"
    ],
    "data": {
      "city": "Malakoff",
      "state": "NY",
      "street": "2992 Cameron Road",
      "zip": "14236"
    },
    "primary": true
  }],
  ...
}
```

Now, `identity` has international friendly field names of `region` and `postal_code` instead of `zip` and `state` as well as a ISO-3166-1 alpha-2 `country` field. Address data fields (`city`, `region`, `street`, `postal_code`, and `country`) are now nullable and are returned with a `null` value when they aren’t available rather than as an empty string. The identity object is now available on the "owners" key of the account, which represents ownership of specific accounts.

```json
"accounts": [{
  ...
  "owners": [{
    "addresses": [{
      "data": {
        "city": "Malakoff",
        "region": "NY",
        "street": "2992 Cameron Road",
        "postal_code": "14236",
        "country": "US",
      },
      "primary": true
    }]
  }],
  ...
}]
```

##### Transactions 

When no transactions are returned from a request, the `transactions` object will now be `null` rather than an empty array.

In addition, the same changes to [Identity](https://plaid.com/docs/api/products/identity/index.html.md) were also made to [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) .

```json
"transactions": [{
  ...
  "location": {
    "address": "300 Post St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94108",
    "lat": null,
    "lon": null
  },
  ...
]}
```

```json
"transactions": [{
  ...
  "location": {
    "address": "300 Post St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94108",
    "country": "US",
    "lat": null,
    "lon": null
  },
  ...
]}
```

##### Institutions 

Changes to the institutions schema effects responses from all of the institutions API endpoints:

*   POST [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch)
*   POST [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget)
*   POST [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id)

The previous version of the Institution schema did not include the country of the institution as part of the response.

```json
"institution": {
  "credentials": [{
    "label": "User ID",
    "name": "username",
    "type": "text"
    }, {
    "label": "Password",
    "name": "password",
    "type": "password"
  }],
  "has_mfa": true,
  "institution_id": "ins_109512",
  "mfa": [
    "code",
    "list",
    "questions",
    "selections"
  ],
  "name": "Houndstooth Bank",
  "products": [
    "auth",
    "balance",
    "identity",
    "transactions"
  ],
  // included when options.include_status is true
  "status": {object}
}
```

```json
"institution": {
  "country_codes": ["US"],
  "credentials": [{
    "label": "User ID",
    "name": "username",
    "type": "text"
    }, {
    "label": "Password",
    "name": "password",
    "type": "password"
  }],
  "has_mfa": true,
  "institution_id": "ins_109512",
  "mfa": [
    "code",
    "list",
    "questions",
    "selections"
  ],
  "name": "Houndstooth Bank",
  "products": [
    "auth",
    "balance",
    "identity",
    "transactions"
  ],
  // included when options.include_status is true
  "status": {object}
}
```

\=\*=\*=\*=

#### Version 2018-05-22 

*   The Auth `numbers` schema has changed to support ACH (US-based) and EFT (Canadian-based) account numbers
*   Added the `iso_currency_code` and `unofficial_currency_code` fields to all [Accounts](https://plaid.com/docs/api/accounts/index.html.md#accounts-get-response-accounts) and [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) responses

Enable support for Canadian institutions from the [Dashboard](https://dashboard.plaid.com/developers/api) and then test in the [Sandbox](https://plaid.com/docs/sandbox/index.html.md) using the test Canadian institution, Tartan-Dominion Bank of Canada (institution ID `ins_43`).

Before, `numbers` was a list of objects, each one representing the account and routing number for an ACH-eligible US checking or savings account:

```json
"numbers": [{
  "account": "9900009606",
  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
  "routing": "011401533",
  "wire_routing": "021000021"
}]
```

**New Auth response (2018-05-22 version)**

Now, `numbers` can have either `ach` (US accounts) or `eft` (Canadian accounts) numbers. Note that the schema for `ach` numbers and `eft` numbers are different from one another.

```json
"numbers": {
   "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
   }],
   "eft": []
}
```

```json
"numbers": {
   "ach":[],
   "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "021",
    "branch": "01140"
   }]
}
```

\=\*=\*=\*=

#### Version 2017-03-08 

The `2017-03-08` version was the first versioned release of the API.

---


# API - Webhooks | Plaid Docs

Webhooks 
=========

#### API reference for webhooks 

Prefer to learn by watching? Our [video tutorial](https://www.youtube.com/watch?v=0E0KEAVeDyc) walks you through the basics of incorporating Plaid webhooks into your application.

Looking for webhook schemas? The reference documentation for specific webhooks ([Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#webhooks) , [Auth](https://plaid.com/docs/api/products/auth/index.html.md#webhooks) , [Assets](https://plaid.com/docs/api/products/assets/index.html.md#webhooks) , [Identity](https://plaid.com/docs/api/products/identity/index.html.md#webhooks-beta) , [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md#webhooks) , [Monitor](https://plaid.com/docs/api/products/monitor/index.html.md) , [Investments](https://plaid.com/docs/api/products/investments/index.html.md#webhooks) , [Liabilities](https://plaid.com/docs/api/products/liabilities/index.html.md#webhooks) , [Payment Initiation](https://plaid.com/docs/api/products/payment-initiation/index.html.md#webhooks) , [Income](https://plaid.com/docs/api/products/income/index.html.md#webhooks) , [Virtual Accounts](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#webhooks) , [Items](https://plaid.com/docs/api/items/index.html.md#webhooks) , and [Transfer](https://plaid.com/docs/api/products/transfer/index.html.md) ) has moved to its respective API reference pages.

\=\*=\*=\*=

#### Introduction to webhooks 

A webhook is an HTTP request used to provide push notifications. Plaid sends webhooks to programmatically inform you about changes to Plaid Items or the status of asynchronous processes. For example, Plaid will send a webhook when an Item is in an error state or has additional data available, or when a non-blocking process (like gathering transaction data or verifying a bank account via micro-deposits) is complete.

To receive Plaid webhooks, set up a dedicated endpoint on your server as a webhook listener that can receive POST requests, then provide this endpoint URL to Plaid as described in the next section. You can also test webhooks without setting up your own endpoint following the instructions in [Testing webhooks in Sandbox](https://plaid.com/docs/api/webhooks/index.html.md#testing-webhooks-in-sandbox) .

\=\*=\*=\*=

#### Configuring webhooks 

Webhooks are typically configured via the `webhook` parameter of [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , although some webhooks (especially those used in contexts where Link tokens are not always required), such as Identity Verification webhooks, are configured via the [Plaid Dashboard](https://dashboard.plaid.com/developers/webhooks) instead. When specifying a webhook, the URL must be in the standard format of `http(s)://(www.)domain.com/` and, if https, must have a valid SSL certificate.

To view response codes and debug any issues with webhook setup, see the [Logs section in the Dashboard](https://dashboard.plaid.com/activity/logs) .

Plaid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses:

*   52.21.26.131
*   52.21.47.157
*   52.41.247.19
*   52.88.82.239

Note that these IP addresses are subject to change.

You can optionally verify webhooks to ensure they are from Plaid. For more information, see [webhook verification](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md) .

\=\*=\*=\*=

#### Webhook retries 

If there is a non-200 response or no response within 10 seconds from the webhook endpoint, Plaid will keep attempting to send the webhook for up to 24 hours. Each attempt will be tried after a delay that is 4 times longer than the previous delay, starting with 30 seconds.

To avoid unnecessary retries, Plaid won't retry webhooks if we detect that the webhook receiver endpoint has rejected more than 90% of webhooks sent by Plaid over the last 24 hours.

\=\*=\*=\*=

#### Best practices for applications using webhooks 

You should design your application to handle duplicate and out-of-order webhooks. Ensure [idempotency](https://martinfowler.com/articles/patterns-of-distributed-systems/idempotent-receiver.html) on actions you take when receiving a webhook. If you drive application state with webhooks, ensure your code doesn't rely on a specific order of webhook receipt.

If you (or Plaid) experience downtime for longer than Plaid's [retry period](https://plaid.com/docs/api/webhooks/index.html.md#webhook-retries) , you will lose webhooks. Ensure your application can recover by implementing endpoint polling or other appropriate logic if a webhook is not received within an expected window. All data present in webhooks is also present in our other APIs.

It's best to keep your receiver as simple as possible, such as a receiver whose only job is to write the webhook into a queue or reliable storage. This is important for two reasons. First, if the receiver does not respond within 10 seconds, the delivery is considered failed. Second, because webhooks can arrive at unpredictable rates. Therefore if you do a lot of work in your receiver - e.g. generating and sending an email - spikes are likely to overwhelm your downstream services, or cause you to be rate-limited if the downstream is a third-party.

\=\*=\*=\*=

#### Testing webhooks in Sandbox 

Webhooks will fire as normal in the Sandbox environment, with the exception of Transfer webhooks. For testing purposes, you can also use [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) , [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) , or [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) to fire a webhook on demand. If you don't have a webhook endpoint configured yet, you can also use a tool such as [Webhook.site](https://webhook.site) or [Request Bin](https://requestbin.com/) to quickly and easily set up a webhook listener endpoint. When directing webhook traffic to third-party tools, make sure you are using Plaid's Sandbox environment and not sending out live data.

\=\*=\*=\*=

#### Example in Plaid Pattern 

For real-life examples of handling webhooks that illustrate how to handle sample transactions and Item webhooks, see [handleTransactionsWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleTransactionsWebhook.js) and [handleItemWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleItemWebhook.js) These files contain webhook handling code for the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app.

---


# API - Webhook verification | Plaid Docs

Verify webhooks 
================

#### API reference for verifying webhooks 

Plaid signs all outgoing webhooks so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the `Plaid-Verification` header (Note: this is the canonical representation of the header field, but HTTP 1.x headers should be handled as [case-insensitive](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) , HTTP 2 headers are always lowercase). The verification process is optional and is not required for your application to handle Plaid webhooks.

The verification process requires understanding JSON Web Tokens (JWTs) and JSON Web Keys (JWKs). More information about these specifications can be found at [jwt.io](http://www.jwt.io) .

Libraries for interpreting and verifying JWKs and JWTs most likely exist in your preferred language. It is highly recommended that you utilize well-tested libraries rather than trying to implement these specifications from scratch.

\=\*=\*=\*=

#### Steps to verify webhooks 

##### Extract the JWT header 

Extract the Plaid-Verification HTTP header from any Plaid webhook (to get a webhook, see [firing webhooks in Sandbox](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) ). The value of the Plaid-Verification header is a JWT, and will be referred to as "the JWT" in following steps.

Using your preferred JWT library, decode the JWT and extract the header without validating the signature. This functionality most likely exists in your preferred JWT library. An example JWT header is shown below.

```json
{
  "alg": "ES256",
  "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
  "typ": "JWT"
}
```

Ensure that the value of the `alg` (algorithm) field in the header is `"ES256"`. Reject the webhook if this is not the case.

Extract the value corresponding to the `kid` (key ID) field. This will be used to retrieve the JWK public key corresponding to the private key that was used to sign this request.

##### Get the verification key 

Use the [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) endpoint to get the webhook verification key.

\=\*=\*=\*=

#### /webhook\_verification\_key/get 

#### Get webhook verification key 

Plaid signs all outgoing webhooks and provides JSON Web Tokens (JWTs) so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the `Plaid-Verification` header.  
The [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) endpoint provides a JSON Web Key (JWK) that can be used to verify a JWT.

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

**key\_id** (required, string)  
The key ID ( kid ) from the JWT header.

```javascript
const request: WebhookVerificationKeyGetRequest = {
  key_id: keyID,
};
try {
  const response = await plaidClient.webhookVerificationKeyGet(request);
  const key = response.data.key;
} catch (error) {
  // handle error
}
```

#### Response fields and example 

**key** (object)  
A JSON Web Key (JWK) that can be used in conjunction with JWT libraries to verify Plaid webhooks

**key->alg** (string)  
The alg member identifies the cryptographic algorithm family used with the key.

**key->crv** (string)  
The crv member identifies the cryptographic curve used with the key.

**key->kid** (string)  
The kid (Key ID) member can be used to match a specific key. This can be used, for instance, to choose among a set of keys within the JWK during key rollover.

**key->kty** (string)  
The kty (key type) parameter identifies the cryptographic algorithm family used with the key, such as RSA or EC.

**key->use** (string)  
The use (public key use) parameter identifies the intended use of the public key.

**key->x** (string)  
The x member contains the x coordinate for the elliptic curve point, provided as a base64url-encoded string of the coordinate's big endian representation.

**key->y** (string)  
The y member contains the y coordinate for the elliptic curve point, provided as a base64url-encoded string of the coordinate's big endian representation.

**key->created\_at** (integer)  
The timestamp when the key was created, in Unix time.

**key->expired\_at** (nullable, integer)  
The timestamp when the key expired, in Unix time.

**request\_id** (string)  
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

```json
{
  "key": {
    "alg": "ES256",
    "created_at": 1560466150,
    "crv": "P-256",
    "expired_at": null,
    "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
    "kty": "EC",
    "use": "sig",
    "x": "hKXLGIjWvCBv-cP5euCTxl8g9GLG9zHo_3pO5NN1DwQ",
    "y": "shhexqPB7YffGn6fR6h2UhTSuCtPmfzQJ6ENVIoO4Ys"
  },
  "request_id": "RZ6Omi1bzzwDaLo"
}
```

##### Validate the webhook 

Interpret the returned `key` as a JWK public key. Using your preferred JWT library, verify the JWT using the JWK. If the signature is not valid, reject the webhook. Otherwise, extract the payload of the JWT. It will look something like the JSON below.

```json
{
  "iat": 1560211755,
  "request_body_sha256": "bbe8e9..."
}
```

Use the issued at time denoted by the `iat` field to verify that the webhook is not more than 5 minutes old. Rejecting outdated webhooks can help prevent replay attacks.

Extract the value of the `request_body_sha256` field. This will be used to check the integrity and authenticity of the webhook body.

Compute the SHA-256 of the webhook body and ensure that it matches what is specified in the `request_body_sha256` field of the validated JWT. If not, reject the webhook. It is best practice to use a constant time string/hash comparison method in your preferred language to prevent timing attacks.

Note that the `request_body_sha256` sent in the JWT payload is sensitive to the whitespace in the webhook body and uses a tab-spacing of 2. If the webhook body is stored with a tab-spacing of 4, the hash will not match.

\=\*=\*=\*=

#### Example implementation 

The following code shows one example method that can be used to verify webhooks sent by Plaid and cache public keys.

```javascript
const compare = require('secure-compare');
const { jwtDecode } = require('jwt-decode'); // syntax for jwtDecode 4.0 or later
const JWT = require('jose');
const sha256 = require('js-sha256');
const plaid = require('plaid');


// Single cached key instead of a Map
let cachedKey = null;


const plaidClient = new plaid.Client({
  clientID: process.env.CLIENT_ID,
  secret: process.env.SECRET,
  env: plaid.environments.sandbox,
});


const verify = async (body, headers) => {
  const signedJwt = JSON.parse(headers)['plaid-verification'];
  const decodedToken = jwtDecode(signedJwt);
  const decodedTokenHeader = jwtDecode(signedJwt, { header: true });
  const currentKeyID = decodedTokenHeader.kid;


  // Fetch key if not already cached
  if (!cachedKey) {
    try {
      const response = await plaidClient.webhookVerificationKeyGet({
        key_id: currentKeyID,
      });
      cachedKey = response.data.key;
    } catch (error) {
      return false;
    }
  }


  // If key is still not set, verification fails
  if (!cachedKey) {
    return false;
  }


  // Validate the signature and iat
  try {
    const keyLike = await JWT.importJWK(cachedKey);
    // This will throw an error if verification fails
    await JWT.jwtVerify(signedJwt, keyLike, {
      maxTokenAge: '5 min',
    });
  } catch (error) {
    return false;
  }


  // Compare hashes
  const bodyHash = sha256(body);
  const claimedBodyHash = decodedToken.request_body_sha256;
  return compare(bodyHash, claimedBodyHash);
};
```

---


# Assets - Create an Asset Report | Plaid Docs

Create an Asset Report 
=======================

#### Learn how to create Asset Reports with the Assets product 

In this guide, we'll start from scratch and walk through how to use [Assets](https://plaid.com/docs/api/products/assets/index.html.md) to generate and retrieve Asset Reports. If a user's Asset Report involves data from multiple financial institutions, the user will need to allow access to each institution, which will in turn enable you to access their data from each institution. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Creating Asset Reports](https://plaid.com/docs/assets/add-to-app/index.html.md#creating-asset-reports) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. This will provide basic information about your app to help users manage their connection on the Plaid Portal at [my.plaid.com](https://my.plaid.com) . The application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include it in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. Asset Reports can consist of user data from multiple financial institutions; users will need to use Link to provide access to each financial institution, providing you with multiple Items. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created. Since, for Assets, users may need to grant access to more than one financial institution via Link, you may need to initialize Link more than once.

In the code samples below, you will need to replace `PLAID_CLIENT_ID` and `PLAID_SECRET` with your own keys, which you can obtain from the [Dashboard](https://dashboard.plaid.com/developers/keys) .

##### Create a link\_token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['assets'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id` for each Item the user provided you with via Link. The `access_token` will allow us to make authenticated calls to the Plaid API for its corresponding financial institution. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token`s and `item_id`s in a secure datastore, as they’re used to access `Item` data and identify `webhooks`, respectively. An `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . An `access_token` should be stored securely and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Creating Asset Reports 

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and create an Asset Report using the [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint.

##### Assets sample request: create 

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { AssetReportCreateRequest } = require('plaid');


const daysRequested = 90;
const options = {
  client_report_id: '123',
  webhook: 'https://www.example.com',
  user: {
    client_user_id: '789',
    first_name: 'Jane',
    middle_name: 'Leah',
    last_name: 'Doe',
    ssn: '123-45-6789',
    phone_number: '(555) 123-4567',
    email: 'jane.doe@example.com',
  },
};
const request: AssetReportCreateRequest = {
  access_tokens: [accessToken],
  days_requested,
  options,
};
// accessTokens is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
try {
  const response = await plaidClient.assetReportCreate(request);
  const assetReportId = response.data.asset_report_id;
  const assetReportToken = response.data.asset_report_token;
} catch (error) {
  // handle error
}
```

Sample response data is below.

```json
{
  "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
  "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
  "request_id": "Iam3b"
}
```

#### Fetching asset data 

Once an Asset Report has been created, it can be retrieved to analyze the user's loan eligibility. For more detailed information on the schema for Asset Reports, see [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) .

Asset Reports are not generated instantly. If you receive a `PRODUCT_NOT_READY` error when calling [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) , the requested Asset Report has not yet been generated. To be alerted when the requested Asset Report has been generated, listen to [Assets webhooks](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) .

##### Assets sample request: get 

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { AssetReportGetRequest } = require('plaid');


const request: AssetReportGetRequest = {
  asset_report_token: assetReportToken,
  include_insights: true,
};
try {
  const response = await plaidClient.assetReportGet(request);
  const assetReportId = response.data.asset_report_id;
} catch (error) {
  // handle error
}
```

Sample response data is below.

```json
{
  "report": {
    "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
    "client_report_id": "123abc",
    "date_generated": "2020-06-05T22:47:53Z",
    "days_requested": 2,
    "items": [
      {
        "accounts": [
          {
            "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
            "balances": {
              "available": 200,
              "current": 210,
              "iso_currency_code": "USD",
              "limit": null,
              "unofficial_currency_code": null
            },
            "days_available": 2,
            "historical_balances": [
              {
                "current": 210,
                "date": "2020-06-04",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2020-06-03",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": ["Alberta Bobbeth Charleson"],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "savings",
            "transactions": [],
            "type": "depository"
          },
          {
            "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
            "balances": {
              "available": null,
              "current": 56302.06,
              "iso_currency_code": "USD",
              "limit": null,
              "unofficial_currency_code": null
            },
            "days_available": 2,
            "historical_balances": [],
            "mask": "8888",
            "name": "Plaid Mortgage",
            "official_name": null,
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": ["Alberta Bobbeth Charleson"],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "mortgage",
            "transactions": [],
            "type": "loan"
          },
          {
            "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
            "balances": {
              "available": null,
              "current": 410,
              "iso_currency_code": "USD",
              "limit": null,
              "unofficial_currency_code": null
            },
            "days_available": 2,
            "historical_balances": [
              {
                "current": 410,
                "date": "2020-06-04",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 410,
                "date": "2020-06-03",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "3333",
            "name": "Plaid Credit Card",
            "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": ["Alberta Bobbeth Charleson"],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "credit card",
            "transactions": [],
            "type": "credit"
          }
        ],
        "date_last_updated": "2020-06-05T22:47:52Z",
        "institution_id": "ins_3",
        "institution_name": "Chase",
        "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "eYupqX1mZkEuQRx",
  "warnings": []
}
```

#### Working with Assets data 

After your initial [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) and [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) requests, you may want your application to fetch updated Asset Reports, provide Audit Copies of Asset Reports, and more. Consult the [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) to explore these and other options.

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Assets - Introduction to Assets | Plaid Docs

Introduction to Assets  
========================

#### Learn how to use Assets to access users' financial information for loan underwriting. 

Get started with Assets

[API Reference](https://plaid.com/docs/api/products/assets/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100)

#### Overview 

Assets data is used to determine whether a user has enough assets to qualify for a loan. Plaid's Assets product allows you to access a user's Asset Report via the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) (JSON) and [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) (PDF) endpoints. Asset Reports are created on a per-user basis and include a snapshot of information about a user's identity, transaction history, account balances, and more.

[Prefer to learn by watching? Get an overview of how Assets works in just 3 minutes!](https://www.youtube.com/watch?v=98Lq6Fb-bwo)

Most new customers should consider [Consumer Report by Plaid Check](https://plaid.com/docs/check/index.html.md) instead of Assets. Consumer Report is an FCRA-compliant product providing underwriting scores and insights, as well as Day 1 Certainty compatible Asset Verification reports for mortgage lending. Assets is recommended for use cases not supported by Consumer Report, such as underwriting outside the US.

For a fuller view of a borrower's financial situation, Assets can be used with [Bank Income](https://plaid.com/docs/income/index.html.md) , which provides user-permissioned income streams derived from deposit activity.

If you need exact copies of a user's statements, see [Statements](https://plaid.com/docs/statements/index.html.md) .

#### No-code integration with the Credit Dashboard 

The Credit Dashboard is currently in beta. To request access, contact your Account Manager. To use the Credit Dashboard for Assets, you must not be using any [Plaid Check](https://plaid.com/docs/check/index.html.md) products.

Assets data is available via a no-code integration through the [Credit Dashboard](https://dashboard.plaid.com/credit) . You can fill out a form with basic information about your end user, such as their name and email address, and indicate how much history you would like to collect and whether you would like to enable [Bank Income](https://plaid.com/docs/income/bank-income/index.html.md) for the session as well. Plaid will then generate a hyperlink that can be used to launch a Plaid-hosted Link session. Plaid can email the link directly to your user (Production only, not available in Sandbox), or you can send it to them yourself.

After the end user successfully completes the Link session, their data will be available in the Dashboard for you to view, archive, or delete. The data shown will be the same data returned by a regular Assets call, in a user-friendly web-based session.

(An image of "Plaid Assets Dashboard: Summary tab with Profile, Income, and Accounts info. Shows user's reference ID, income, and bank accounts.")

This integration is also compatible with Income, and you can enable Assets and Income in the same session.

Once you are enabled for the Credit Dashboard, all new sessions, including ones created via the API, will be displayed in the Dashboard.

Data from Link sessions created via the Credit Dashboard cannot be accessed via the Plaid API. If you require programmatic access to data, use the [code-based integration flow](https://plaid.com/docs/assets/index.html.md#integration-overview) instead.

#### Integration overview 

There are a few steps you will need to take to obtain an Asset Report for a particular user.

1.  First, using the Link flow, [create Items](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) for each of the user's financial institutions; in doing so, you will obtain an `access_token` for each institution. You can use these tokens to obtain an Asset Report as long as the `access_token` was generated with `assets` included in Link's `product` array. With Assets, the user, upon using Link to authenticate with their financial institution, will need to provide consent for Plaid to access account balances, account holder information, and transaction history for that institution. Should the user revoke access via [my.plaid.com](https://my.plaid.com/) , Plaid will notify you via a [webhook](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) .
    
2.  Once you have the required `access_token`s, call the [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint to create an Asset Report. Note that Asset Reports are not created instantly. When the Asset Report is ready, you will be notified via a [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook. If low latency is important to your use case, you can call [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) with `options.add_ons` set to `["fast_assets"]`. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report.
    
3.  After receiving the [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook, you can retrieve an Asset Report in JSON format by calling the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint. To retrieve an Asset Report in PDF format, call the [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) endpoint. To retrieve an Asset Report with cleaned and categorized transactions as well as additional information about merchants and locations in JSON format, call the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint with `include_insights=true`. If you enabled Fast Assets when calling [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) , you can request the Fast version of the Asset Report by calling [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) with `fast_report=true`.
    
4.  Sometimes, third party auditors need to see Asset Reports to audit lenders' decision making processes. To provide an Audit Copy of an Asset Report to a requesting third party, call the [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) endpoint and provide the auditor with an `audit_copy_token`. The auditor needs to be integrated with Plaid in order to view Audit Copies. Currently, Fannie Mae, Freddie Mac, and Ocrolus are the only auditors integrated with Plaid.
    

```json
{
    "report": {
        "asset_report_id": "ebb8f490-8f45-4c93-a6c3-5801bf92c3ff",
        "client_report_id": null,
        "date_generated": "2023-12-18T07:20:25Z",
        "days_requested": 2,
        "items": [
            {
                "accounts": [
                    {
                        "account_id": "1Gd3X8NmgLFVn47RorabTJ7Bvy8vBqfpaG5Ky",
                        "balances": {
                            "available": null,
                            "current": 320.76,
                            "iso_currency_code": "USD",
                            "limit": null,
                            "unofficial_currency_code": null
                        },
                        "days_available": 0,
                        "historical_balances": [],
                        "mask": "5555",
                        "name": "Plaid IRA",
                        "official_name": null,
                        "owners": [
                            {
                                "addresses": [
                                    {
                                        "data": {
                                            "city": "Malakoff",
                                            "country": "US",
                                            "postal_code": "14236",
                                            "region": "NY",
                                            "street": "2992 Cameron Road"
                                        },
                                        "primary": true
                                    }
                                ],
                                "emails": [
                                    {
                                        "data": "accountholder0@example.com",
                                        "primary": true,
                                        "type": "primary"
                                    }
                                ],
                                "names": [
                                    "Alberta Bobbeth Charleson"
                                ],
                                "phone_numbers": [
                                    {
                                        "data": "1112225555",
                                        "primary": false,
                                        "type": "mobile"
                                    }
                                ]
                            }
                        ],
                        "ownership_type": null,
                        "subtype": "ira",
                        "transactions": [],
                        "type": "investment"
                    },
                    {
                        "account_id": "7B73zkZlnLfeWMvkAlxpslbR4PM4RECdaKgll",
                        "balances": {
                            "available": 100,
                            "current": 110,
                            "iso_currency_code": "USD",
                            "limit": null,
                            "unofficial_currency_code": null
                        },
                        "days_available": 2,
                        "historical_balances": [
                            {
                                "current": 110,
                                "date": "2023-12-17",
                                "iso_currency_code": "USD",
                                "unofficial_currency_code": null
                            },
                            {
                                "current": 116.33,
                                "date": "2023-12-16",
                                "iso_currency_code": "USD",
                                "unofficial_currency_code": null
                            }
                        ],
                        "mask": "0000",
                        "name": "Plaid Checking",
                        "official_name": "Plaid Gold Standard 0% Interest Checking",
                        "owners": [
                            {
                                "addresses": [
                                    {
                                        "data": {
                                            "city": "Malakoff",
                                            "country": "US",
                                            "postal_code": "14236",
                                            "region": "NY",
                                            "street": "2992 Cameron Road"
                                        },
                                        "primary": true
                                    },
                                    {
                                        "data": {
                                            "city": "San Matias",
                                            "country": "US",
                                            "postal_code": "93405-2255",
                                            "region": "CA",
                                            "street": "2493 Leisure Lane"
                                        },
                                        "primary": false
                                    }
                                ],
                                "emails": [
                                    {
                                        "data": "accountholder0@example.com",
                                        "primary": true,
                                        "type": "primary"
                                    }
                                ],
                                "names": [
                                    "Alberta Bobbeth Charleson"
                                ],
                                "phone_numbers": [
                                    {
                                        "data": "1112223333",
                                        "primary": false,
                                        "type": "home"
                                    }
                                ]
                            }
                        ],
                        "ownership_type": null,
                        "subtype": "checking",
                        "transactions": [
                            {
                                "account_id": "7B73zkZlnLfeWMvkAlxpslbR4PM4RECdaKgll",
                                "amount": 6.33,
                                "date": "2023-12-09",
                                "iso_currency_code": "USD",
                                "original_description": "Uber 072515 SF**POOL**",
                                "pending": false,
                                "transaction_id": "mqdZ1xRbjau73pER6NrPSZQXZKQdN8CgLKrXA",
                                "unofficial_currency_code": null
                            }
                        ],
                        "type": "depository"
                    }
                ],
                "date_last_updated": "2023-12-18T07:16:21Z",
                "institution_id": "ins_3",
                "institution_name": "Chase",
                "item_id": "KEv98XqZ7yudGRpDqaxJsZ3PKDGzR8CRM13nr"
            }
        ],
        "user": {
            "client_user_id": null,
            "email": null,
            "first_name": null,
            "last_name": null,
            "middle_name": null,
            "phone_number": null,
            "ssn": null
        }
    },
    "request_id": "AYRjla7HgW4nKM9",
    "warnings": []
}
```

The `report` field of the above object contains the body of the Asset Report. This field consists of several subfields that contain information about the date and time the Asset Report was created; data submitted about the user; and information about Items, containing the user's historical balances, identity information, and more for each of the user's financial institutions. For a full explanation of the `report` field and its subfields, consult the [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) .

#### Assets webhooks 

When you create an Asset Report, Plaid aggregates account balances, account holder identity information, and transaction history for the duration specified. If you attempt to retrieve an Asset Report before the requested data has been collected, you’ll receive a response with the HTTP status code 400 and a Plaid error code of `PRODUCT_NOT_READY`.

To remove the need for polling, Plaid sends a webhook to the URL you supplied when creating the Asset Report once the Report has been generated. If generation fails, the webhook will indicate why. For examples of webhooks corresponding to successful and unsuccessful Asset Report generation, see the [API Reference for Assets webhooks](https://plaid.com/docs/api/products/assets/index.html.md#webhooks) .

#### Refreshing Asset Reports 

Asset Reports can either be created or removed; they cannot be updated. To retrieve up-to-date information about users' transactions and balances, call the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint. This endpoint, when used, creates a new Asset Report based on the corresponding existing Asset Report.

#### Getting an Asset Report for an existing Item 

If your user has already connected their account to your application for a different product, you can add Assets to the existing Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

To do so, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, populate the `access_token` field with the access token for the Item, and set the `products` array to `["assets"]`. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Asset Report consent step. Otherwise, they will be prompted to complete the full Link flow.

#### Financial Account Matching 

If you are already using [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , you can enhance your verification process by enabling [Financial Account Matching](https://plaid.com/docs/identity-verification/index.html.md#financial-account-matching) in your Identity Verification template. This feature allows you to compare the data collected during KYC with the bank account data collected when creating an Asset Report. To ensure accurate matching, it's important to maintain consistency in the `client_user_id` used for end users across all products.

#### Financial Insights Reports (UK/EU only) 

In the UK and EU, the Financial Insights Report, including risk and affordability insights, is available as an optional add-on to Assets. Risk insights provides details on instances of potential risks such as loan disbursements, loan payments, gambling, bank penalties, and negative balances. Affordability insights provides insights based on spending / income ratios, considering factors such as essential vs. non-essential spend and other financial commitments.

Like Asset Reports, Financial Insights Reports are available in both JSON and PDF format. [View a sample Financial Insights Report (UK/EU only) PDF](https://plaid.com/documents/sample-financial-insights-report.pdf) .

To learn more about Financial Insights Reports or to request pricing details, [contact Sales](https://plaid.com/contact/) or your Plaid Account Manager.

#### Testing Assets 

Assets can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) without any additional permissions and can be tested in Limited Production once your Production request is approved.

Plaid provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) with test data for testing Assets in Sandbox, beyond that provided by the default Sandbox user. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) .

#### Attributes library 

Plaid provides a GitHub [Credit attributes library](https://github.com/plaid/credit-attributes) with Python scripts that can be used to derive various useful information from Asset Reports.

#### Assets pricing 

Assets is billed on a [flexible fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flexible-fee) ; the cost will depend on the number of Items in the Asset Report (there is an additional cost for Asset Reports with more than 5 Items), as well as whether Additional History (over 61 days of history) has been requested for the report. Audit copies and PDF Asset Reports are billed based on a [per-request model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

To learn more about building with Assets, see [Create an Asset Report](https://plaid.com/docs/assets/add-to-app/index.html.md) and the [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) .

For a more detailed overview of the steps involved in creating a full implementation of Plaid Assets, see the [Plaid Assets Solution Guide](https://plaid.com/documents/plaid-assets-solution-guide.pdf) .

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Assets - Assets partners | Plaid Docs

Assets Partners 
================

#### Find providers who have partnered with Plaid to provide Assets verification 

\=\*=\*=\*=

#### Overview 

| Partner | Description |
| --- | --- |
| [Alloy](https://plaid.com/docs/assets/partnerships/alloy/index.html.md) | Offers identity data orchestration and credit decisioning to financial services companies looking to address fraud and uphold compliance (US only) |
| [Ocrolus](https://plaid.com/docs/assets/partnerships/ocrolus/index.html.md) | Provides digitized Asset documentation verification (US only) |

For more information, see the list of partners in the [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) .

---


# Assets - Ocrolus | Plaid Docs

Add Ocrolus to your app 
========================

#### Use Ocrolus with Plaid Assets to digitize data collection 

(An image of "Logos of Plaid and Ocrolus side by side.")

  

Plaid and Ocrolus have partnered to offer lenders an easier way to access bank data to make informed loan decisions. Plaid enables businesses to instantly connect a customer's bank account, giving them the ability to authenticate and retrieve account details directly from the financial institution. Ocrolus digitizes bank and credit card statements from all US financial institutions to help lenders digitize their data collection for cash-flow analysis.

With the Plaid + Ocrolus integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid’s front-end module. Plaid will retrieve the relevant bank information and pass it to Ocrolus for further digestion and reporting in a seamless, secure fashion. Plaid’s mobile-friendly module handles input validation, error handling, and multi-factor authentication, providing a seamless onboarding experience to convert more users for your business.

#### Getting started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/docs/link/index.html.md) , a drop-in integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to create or be an existing [Ocrolus customer](https://www.ocrolus.com/get-api-keys/) in order to add a bank account.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment and verification of assets. From there, you'll receive a Plaid `access_token`, which you can use generate an Ocrolus `processor_token` and/or `audit_copy_token`, depending on your use case, which allow you to quickly and securely verify banking information via the [Ocrolus API](https://www.ocrolus.com/) without having to store that sensitive information yourself.

#### Instructions 

##### Set up your Plaid and Ocrolus accounts 

You'll need accounts at both Plaid and Ocrolus in order to use the Plaid + Ocrolus integration. You'll also need to enable your Plaid account for the Ocrolus integration.

First, you will need to work with the Ocrolus team to [sign up for an Ocrolus account](https://www.ocrolus.com/get-api-keys/) , if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup/ocrolus) . Your account will be automatically enabled for integration access.

To verify that your Plaid account is enabled for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Ocrolus to enable the integration.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. View the [documentation](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for a full list of `link_token` configurations.

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['assets'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Ocrolus `processor_token`.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onLoad: function() {
          // The Link module finished loading.
      },
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has
        // successfully authenticated and selected an account to
        // use.
        //
        // When called, you will send the public_token
        // and the selected account ID, metadata.account_id,
        // to your backend app server.
        //
        // sendDataToBackendServer({
        //   public_token: public_token,
        //   account_id: metadata.account_id
        // });
        console.log('Public Token: ' + public_token);
        console.log('Customer-selected account ID: ' + metadata.account_id);
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error
            // prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent
        // API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

Once you have the `access_token` for the Item, you can create an Ocrolus `processor_token` and/or `audit_copy_token`. You'll send these tokens to Ocrolus and they will use them to securely retrieve banking information from Plaid.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
  AssetReportAuditCopyCreateRequest,
} = require('plaid');
// Change sandbox to production to test with live users or to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: PUBLIC_TOKEN,
  });
  const accessToken = tokenResponse.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'ocrolus',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.processor_token;


  // Create an Asset Report for the specific access token.
  const request: AssetReportCreateRequest = {
    access_tokens: [accessToken],
    days_requested: 90,
    options: {},
  };
  const response = await plaidClient.assetReportCreate(request);
  const assetReportId = response.data.asset_report_id;
  const assetReportToken = response.data.asset_report_token;


  // Create an audit copy token for the Asset Report.
  const request: AssetReportAuditCopyCreateRequest = {
    asset_report_token: createResponse.data.asset_report_token,
    auditor_id: 'ocrolus',
  };
  const response = await plaidClient.assetReportAuditCopyCreate(request);
  const auditCopyToken = response.data.audit_copy_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "UNIQUE_REQUEST_ID"
}
```

For a valid `audit_copy_token` request, the API will return a JSON response similar to:

```json
{
  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
  "request_id": "UNIQUE_REQUEST_ID"
}
```

For more information on creating Asset Report `audit_copy_tokens`, see the documentation for the [Assets](https://plaid.com/docs/assets/index.html.md) product.

##### Testing your Ocrolus integration 

You can create Ocrolus `processor_tokens` in Sandbox (sandbox.plaid.com, allows testing with simulated users). To test the integration in Sandbox mode, use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) when launching Link with a `link_token` created in the Sandbox environment.

To move to Production, [request access](https://dashboard.plaid.com/settings/team/products) from the Dashboard. You will want to ensure that you have valid Ocrolus Production credentials prior to connecting bank accounts in the Ocrolus API with Plaid.

#### Support and questions 

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth - Add Auth to your app | Plaid Docs

Add Auth to your app 
=====================

#### Use Auth to connect user bank accounts 

In this guide, we'll demonstrate how to add [Auth](https://plaid.com/docs/api/products/auth/index.html.md) to your app so that you can connect to your users' bank accounts and obtain the information needed to set up funds transfers.

If you're already familiar with using Plaid and are set up to make calls to the Plaid API, see [Getting Auth data](https://plaid.com/docs/auth/add-to-app/index.html.md#getting-auth-data) . If you're interested in using a Plaid partner, such as Stripe or Dwolla, to process payments, see [Moving funds with a payment partner](https://plaid.com/docs/auth/add-to-app/index.html.md#moving-funds-with-a-payment-partner) .

Prefer to learn by watching? A [video guide](https://youtu.be/FlZ5nzlIq74) is available for this topic.

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item using Link 

These instructions cover Link for web applications. For instructions on using Link in mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Plaid Link is the client-side component that your users interact with to securely connect their bank accounts to your app. An [Item](https://plaid.com/docs/quickstart/glossary/index.html.md#item) is created when a user successfully logs into their financial institution using Link. An Item represents a single login at a financial institution. Items do not represent individual bank accounts, although all bank accounts are associated with an Item. For example, if a user has a single login at a bank that allows them to access both a checking account and a savings account, only a single Item would be associated with both of the accounts.

When using Auth, you will typically only need access to the specific bank account that will be used to transfer funds, rather than all of the accounts a user may have at an institution. Because of this, it is recommended that you configure Link with [Account Select](https://plaid.com/docs/link/customization/index.html.md#account-select) when using Auth. Configuring Link with Account Select will limit unnecessary access to user accounts. You can [enable Account Select from the Dashboard](https://dashboard.plaid.com/link/account-select) .

To create an Item, you'll first need to create a [Link token](https://plaid.com/docs/quickstart/glossary/index.html.md#link-token) on your application server. You can create a Link token by calling the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client-side of your application, you'll initialize Link with using the Link token you created.

The code samples below demonstrate how to create a Link token and how to initialize Link using the token.

##### Create a Link token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Initialize Link with the Link token 

If your use case involves a pay-by-bank payments flow where the end user can choose between paying via a credit card and paying via a bank account, it is highly recommended to use the [Embedded experience](https://plaid.com/docs/link/embedded-institution-search/index.html.md) for Link to increase uptake of pay-by-bank. If your use case is an account opening or funding flow that requires the customer to use a bank account, or has a surcharge for credit card use, use the standard Link experience.

Select group for content switcher

Account funding (standard Link)Pay by Bank (Embedded Link)

```javascript
const handler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Upon successful linking of a bank account,
    // Link will return a public token.
    // Exchange the public token for an access token
    // to make calls to the Plaid API.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onLoad: () => {},
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


handler.open();
```

The sample code below is for JavaScript. For more examples for other platforms, see [Embedded Link](https://plaid.com/docs/link/embedded-institution-search/index.html.md#integration-steps) .

```javascript
// The container at `#plaid-embedded-link-container` will need to be sized in order to
// control the size of the embedded Plaid module
const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container');


Plaid.createEmbedded(
    {
      token: 'GENERATED_LINK_TOKEN',
      onSuccess: (public_token, metadata) => {},
      onLoad: () => {},
      onExit: (err, metadata) => {},
      onEvent: (eventName, metadata) => {},
    },
    embeddedLinkOpenTarget,
);
```

#### Obtain an access token 

When a user successfully links an Item via Link, the [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback will be called. The `onSuccess` callback returns a [public token](https://plaid.com/docs/quickstart/glossary/index.html.md#public-token) . On your application server, exchange the public token for an [access token](https://plaid.com/docs/quickstart/glossary/index.html.md#access-token) and an [Item ID](https://plaid.com/docs/quickstart/glossary/index.html.md#item-id) by calling `/item/public_token/exchange/`. The access token will allow you to make authenticated calls to the Plaid API.

Store the access token and Item ID in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access token will remain valid unless you actively expire it via rotation or remove it by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) on the corresponding Item. For security purposes, never store the access token in client-side code. The public token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

##### Exchange public token for an access token 

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Getting Auth data 

Now that you have an access token, you can begin making authenticated calls to the Plaid API. If you are processing payments yourself, the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint to retrieve the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's accounts. You can then supply these to your payment system. If you are using a Plaid partner to move funds, you will not need to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . Instead, see [Moving funds with a payment partner](https://plaid.com/docs/auth/add-to-app/index.html.md#moving-funds-with-a-payment-partner) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { AuthGetRequest } = require('plaid');


// Call /auth/get and retrieve account numbers for an Item
const request: AuthGetRequest = {
  access_token: access_token,
};
try {
  const response = await plaidClient.authGet(request);
  const accountData = response.data.accounts;
  if (response.data.numbers.ach.length > 0) {
    // Handle ACH numbers (US accounts)
    const achNumbers = response.data.numbers.ach;
  }
  if (response.data.numbers.eft.length > 0) {
    // Handle EFT numbers (Canadian accounts)
    const eftNumbers = response.data.numbers.eft;
  }
  if (response.data.numbers.international.length > 0) {
    // Handle International numbers
    const internationalNumbers = response.data.numbers.international;
  }
  if (response.data.numbers.bacs.length > 0) {
    // Handle BACS numbers (British accounts)
    const bacsNumbers = response.data.numbers.bacs;
  }
} catch (error) {
  //handle error
}
```

Example response data is below. Note that this is test account data; real accounts would not include all four sets of numbers.

```json
{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": {
        "available": 100,
        "current": 110,
        "limit": null,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "mask": "9606",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "numbers": {
    "ach": [
      {
        "account": "9900009606",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [
      {
        "account": "111122223333",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "institution": "021",
        "branch": "01140"
      }
    ],
    "international": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "bic": "NWBKGB21",
        "iban": "GB29NWBK60161331926819"
      }
    ],
    "bacs": [
      {
        "account": "31926819",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "sort_code": "601613"
      }
    ]
  },
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": ["assets", "auth"],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "m8MDnv9okwxFNBV"
}
```

#### Moving funds with a payment partner 

You can move money via ACH transfer by pairing Auth with one of Plaid's payment partners. When using a partner to move money, the partner's payments service will initiate the transfer; Plaid does not function as the payment processor. For the full list of payments platforms who have partnered with Plaid to provide ACH money movement, see [Auth Partnerships](https://plaid.com/docs/auth/partnerships/index.html.md) .

To move money using a Plaid partner, first create an Item using Link and obtain an access token as described above. Then, instead of calling Plaid's Auth endpoints, call one of Plaid's [processor token endpoints](https://plaid.com/docs/api/processors/index.html.md) to create a processor token. You can then send this processor token to one of Plaid's partners by using endpoints that are specific to the payment platform. Refer to the partner's technical documentation for more information. Using a partner to transfer funds gives you access to payment functionality while freeing you from having to securely store sensitive bank account information.

The sample code below demonstrates a call to [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) using Dwolla as the payment processor.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { ProcessorTokenCreateRequest } = require('plaid');


try {
  // Create a processor token for a specific account id
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'dwolla',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.processor_token;
} catch (error) {
  // handle error
}
```

#### Tutorial and example code in Plaid Pattern 

For a real-life example of an app that incorporates Auth, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L135) .

For a step-by-step tutorial on how to implement account funding, [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

#### Next steps 

Once Auth is implemented in your app, see [Micro-deposit and database verification](https://plaid.com/docs/auth/coverage/index.html.md) to make sure your app is supporting the maximum number of institutions and verification methods (US only).

If your use case is an account funding use case, see [the Account funding solutions guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for a set of recommendations on how to implement Auth.

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Auth - Automated Micro-deposits | Plaid Docs

Automated Micro-deposits 
=========================

#### Learn how to authenticate your users in a secure and frictionless micro-deposit flow 

#### The Automated Micro-deposit flow 

The Automated Micro-deposits authentication flow is supported for an additional 1,900 financial institutions in the US where Instant Auth is not available, accounting for approximately <1% of depository accounts. Plaid will make a single micro-deposit and then automatically verify it within one to two business days.

(An image of "Plaid automated micro-deposit flow: Enter credentials, select account, verify routing and account number, enter name, confirm deposit.")

You can try out the Automated Micro-deposits flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=5) . See more details in our [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-automated-micro-deposits) .

A user connects their financial institution using the following connection flow:

1.  Starting on a page in your app, the user clicks an action that opens Plaid Link, with the correct Auth [configuration](https://plaid.com/docs/auth/coverage/automated/index.html.md#configure--create-a-link_token) .
2.  Inside of Plaid Link, the user selects their institution, authenticates with their credentials, provides their account and routing number, and enters in their legal name.
3.  Upon [successful authentication](https://plaid.com/docs/auth/coverage/automated/index.html.md#exchange-the-public-token) , Link closes with a `public_token` and a `metadata` account status of `pending_automatic_verification`.
4.  Behind the scenes, Plaid sends a single micro-deposit to the user's account and will automatically verify the deposited amounts within one to two business days.
5.  When verification succeeds or fails, Plaid sends an [Auth webhook](https://plaid.com/docs/auth/coverage/automated/index.html.md#handle-auth-webhooks) , which you can use to notify the user that their account is ready to move money. Once this step is done, your user's Auth data is verified and [ready to fetch](https://plaid.com/docs/auth/coverage/automated/index.html.md#fetch-auth-data) .

#### Configure & Create a link\_token 

Create a `link_token` with the following parameters:

*   `products` array containing `auth` or `transfer` -- unlike with Same-Day Micro-deposits, you can also include other products besides `auth` or `transfer` when creating a Link token for use with Automated Micro-deposits, but `auth` or `transfer` must be present.
*   `country_codes` set to `['US']` – Micro-deposit verification is currently only available in the United States.
*   A `webhook` URL to receive a POST HTTPS request sent from Plaid's servers to your application server, after Automated Micro-deposits succeeds or fails verification of a user's micro-deposits.
*   `auth` object should specify `"automated_microdeposits_enabled": true`

```javascript
const request: LinkTokenCreateRequest = {
  user: { client_user_id: new Date().getTime().toString() },
  client_name: 'Plaid App',
  products: [Products.Auth],
  country_codes: [CountryCode.Us],
  language: 'en',
  auth: {
    automated_microdeposits_enabled: true,
  },
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

#### Initialize Link with a link\_token 

After creating a `link_token` for the `auth` product, use it to initialize Plaid Link.

When the user inputs their username and password, and account and routing numbers for the financial institution, the `onSuccess()` callback function will return a `public_token`, with `verification_status` equal to `'pending_automatic_verification'`.

```javascript
const linkHandler = Plaid.create({
  // Fetch a link_token configured for 'auth' from your app server
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token and accounts to your app server
    $.post('/exchange_public_token', {
      publicToken: public_token,
      accounts: metadata.accounts,
    });


    metadata = {
      ...,
      link_session_id: String,
      institution: { name: 'Bank of the West', institution_id: 'ins_100017' },
      accounts: [{
        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
        mask: '1234',
        name: null,
        type: 'depository',
        subtype: 'checking',
        verification_status: 'pending_automatic_verification'
      }]
    }
  },
  // ...
});


// Open Link on user-action
linkHandler.open();
```

##### Display a "pending" status in your app 

Because Automated verification usually takes between one to two days to complete, we recommend displaying a UI in your app that communicates to a user that verification will occur automatically and is currently pending.

You can use the `verification_status` key returned in the `onSuccess` `metadata.accounts` object once Plaid Link closes successfully.

```javascript
verification_status: 'pending_automatic_verification';
```

You can also [fetch the verification\_status](https://plaid.com/docs/auth/coverage/automated/index.html.md#check-the-account-verification-status-optional) for an Item's account via the Plaid API to obtain the latest account status.

#### Exchange the public token 

In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` received in the `onSuccess` callback to obtain an `access_token`. Persist the returned `access_token` and `item_id` in your database in relation to the user.

Note that micro-deposits will only be delivered to the ACH network in the Production environment. To test your integration outside of Production, see [Testing automated micro-deposits in Sandbox](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-automated-micro-deposits) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
// publicToken and accountID are sent from your app to your backend-server
const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';


// Obtain an access_token from the Link public_token
const response = await client
  .itemPublicTokenExchange({
    public_token: publicToken,
  })
  .catch((err) => {
    // handle error
  });
const accessToken = response.access_token;
```

```json
{
  "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "m8MDnv9okwxFNBV"
}
```

#### Handle Auth webhooks 

Before you can call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to fetch Auth data for a user's `access_token`, a micro-deposit first need to post successfully to the user's bank account. Because Plaid uses Same Day ACH to send a single micro-deposit amount, this process usually takes between one to two days.

Once the deposit has arrived in the user's account, Plaid will automatically verify the deposit transaction and send an [AUTOMATICALLY\_VERIFIED](https://plaid.com/docs/api/products/auth/index.html.md#automatically_verified) webhook to confirm the account and routing numbers have been successfully verified.

Attempting to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) on an unverified `access_token` will result in a [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error.

```json
> POST https://your_app_url.com/webhook


{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm",
  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
}
```

Occasionally automatic verification may fail, likely due to erroneous user input, such as an incorrect account and routing number pair. If the Item is unable to be verified within seven days, Plaid will send a [VERIFICATION\_EXPIRED](https://plaid.com/docs/api/products/auth/index.html.md#verification_expired) webhook. When verification fails, the Item is permanently locked; we recommend prompting your user to retry connecting their institution via Link.

```json
> POST https://your_app_url.com/webhook


{
  "webhook_type": "AUTH",
  "webhook_code": "VERIFICATION_EXPIRED",
  "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm",
  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
}
```

If Plaid encounters an `ITEM_LOGIN_REQUIRED` error during attempted validation, this may mean that Plaid lost access to the user's account after sending this micro-deposit but before being able to verify it. If this occurs, send the user through the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow to re-verify their account.

The example code below shows how to handle `AUTOMATICALLY_VERIFIED` and `VERIFICATION_EXPIRED` webhooks and call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to retrieve account and routing data.

If you are using the Sandbox environment, you can use the [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) endpoint to test your integration.

Select group for content switcher

Current librariesLegacy libraries

```javascript
// This example uses Express to receive webhooks
const app = require('express')();
const bodyParser = require('body-parser');
app.use(bodyParser);


app.post('/webhook', async (request, response) => {
  const event = request.body;


  // Handle the event
  switch (event.webhook_code) {
    case 'AUTOMATICALLY_VERIFIED':
      const accessToken = lookupAccessToken(event.item_id);
      const request: AuthGetRequest = { access_token: accessToken };
      const authResponse = await client.authGet(request);
      const numbers = authResponse.numbers;
      break;
    case 'VERIFICATION_EXPIRED':
      // handle verification failure; prompt user to re-authenticate
      console.error('Verification failed for', event.item_id);
      break;
    default:
      // Unexpected event type
      return response.status(400).end();
  }


  // Return a response to acknowledge receipt of the event
  response.json({ received: true });
});


app.listen(8000, () => console.log('Running on port 8000'));
```

#### Check the account verification status (optional) 

In some cases you may want to implement logic to display the `verification_status` of an Item that is pending automated verification in your app. The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) API endpoint allows you to query this information.

For non-programmatic access to this information, you can use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification/) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
// Fetch the accountID and accessToken from your database
const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
const request: AccountsGetRequest = {
  access_token: accessToken,
};
const response = await client.accountsGet(request).catch((err) => {
  // handle error
});
const account = response.accounts.find((a) => a.account_id === accountID);
const verificationStatus = account.verification_status;
```

```json
{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": { Object },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Checking",
      "type": "depository"
      "subtype": "checking",
      "verification_status":
        "pending_automatic_verification" |
        "automatically_verified" |
        "verification_expired",
    },
    ...
  ],
  "item": { Object },
  "request_id": String
}
```

#### Fetch Auth data 

Finally, we can retrieve Auth data once automated verification has succeeded:

Select group for content switcher

Current librariesLegacy libraries

```javascript
const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';


// Instantly fetch Auth numbers
const request: AuthGetRequest = {
  access_token: accessToken,
};
const response = await client.authGet(request).catch((err) => {
  // handle error
});
const numbers = response.numbers;
```

```json
{
  "numbers": {
    "ach": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "account": "1111222233330000",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [],
    "international": [],
    "bacs": []
  },
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": { Object },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "verification_status": "automatically_verified",
      "subtype": "checking" | "savings",
      "type": "depository"
    }
  ],
  "item": { Object },
  "request_id": "m8MDnv9okwxFNBV"
}
```

Check out the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) API reference documentation to see the full Auth request and response schema.

#### Handling Link events 

For a user who goes through the Automated Micro-deposit flow, the `TRANSITION_VIEW (view_name = NUMBERS)` event will occur after `SUBMIT_CREDENTIALS`, and in the `onSuccess` callback the `verification_status` will be `pending_automatic_verification`.

```bash
OPEN (view_name = CONSENT)
TRANSITION_VIEW view_name = SELECT_INSTITUTION)
SEARCH_INSTITUTION
SELECT_INSTITUTION
TRANSITION_VIEW (view_name = CREDENTIAL)
SUBMIT_CREDENTIALS
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = MFA, mfa_type = code)
SUBMIT_MFA (mfa_type = code)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = SELECT_ACCOUNT)
TRANSITION_VIEW (view_name = NUMBERS)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess (verification_status: pending_automatic_verification)
```

#### Same Day Micro-deposits 

Integrate the manual micro-deposit flow

[View guide](https://plaid.com/docs/auth/coverage/same-day/index.html.md)

#### Testing in Sandbox 

Learn how to test each Auth flow in the Sandbox

[View guide](https://plaid.com/docs/auth/coverage/testing/index.html.md)

---


# Auth - Database Auth | Plaid Docs

Database Auth 
==============

#### Evaluate a manually entered account using Plaid network data  

#### Overview 

Database Auth can increase conversion by providing instant account verification when end users cannot, or do not want to, log into their financial institution to verify their account. Examples include end users at banks that are not supported by Plaid, or users who need to verify a business bank account but who don't have access to manage the account via online banking. With Database Auth, users can instead enter their account and routing number manually.

Database Auth verifies account and routing numbers by checking the information provided against Plaid's known account numbers, leveraging Plaid's database of over 200 million verified accounts. If no match is found, Plaid will check the account number format against known usages by the institution associated with the given routing number. Database Auth will provide a verification status of 'pass', 'pass with caution', or 'fail' and a set of attributes that contributed to that status, such as whether a match was found or whether Plaid fell back to checking account number formats.

Database Auth does not verify that the user has access to the bank account and does also not fully guarantee that the account exists. Database Auth does not create a live connection to the bank account and cannot be used to check real-time balances (although it is compatible with anti-risk products such as Signal and Identity Match). For these reasons, Database Auth should not be enabled where there is a very high risk of fraud or ACH returns.

Database Auth is available for Auth flows the United States. In Canada, Database Auth functionality is provided by the [Database Insights](https://plaid.com/docs/auth/coverage/database/index.html.md) feature.

You can try out the Database Auth flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=6) .

##### Database Auth flow 

1.  Starting on a page in your app, the user clicks an action that opens Plaid Link.
2.  Inside of Plaid Link, the user selects an option that triggers the manual verification flow. This could occur because the user opted in to the manual flow (if Auth Type Select is enabled) or because their institution does not support Instant Auth.
3.  The user will be prompted to enter their name, routing number, and account number.
4.  Based on rules you have configured, the user will either see a success screen or a failure screen, or be prompted to fall back to micro-deposit-based verification.

#### Implementation steps 

1.  Create a `link_token` with the following parameters:
    *   The `products` array should include `auth` or `transfer` only, and no other products.
    *   If you are enabling Identity Match, put `identity` in the `required_if_supported_products` array, as putting it in the `products` array will prevent Database Auth from activating.
    *   If you plan to use Signal, put `signal` in the `additional_consented_products` or `required_if_supported_products` array. Putting it in the `products` array will prevent Database Auth from activating.
    *   No other products besides Signal and Identity are compatible with Database Auth Items. To enable other products for Items where Database Auth is not used, put those products in the `additional_consented_products` array.
    *   `country_codes` should be set to `['US']` – Database Auth is currently only available in the United States.
2.  In the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , ensure "Manage via Dashboard" is selected, and enable "Verify with Database Verification".
3.  Configure the rules:
    *   (Recommended for most customers) To use Plaid's rules-based, customizable, no-code evaluation logic, select "For certain Database Auth results, fallback".
    *   To use your own evaluation logic, select "For any Database Auth result, complete Link". This option is designed for customers who require more fine-grained control of the Link flow beyond what the ruleset configuration allows, or who have highly sophisticated fraud evaluation systems and require more custom logic. See [Using your own evaluation logic](https://plaid.com/docs/auth/coverage/database-auth/index.html.md#using-your-own-evaluation-logic-advanced) .
4.  [Open Link](https://plaid.com/docs/link/index.html.md) according to the instructions for your platform, using the `link_token` created earlier.
5.  After the end user completes the Link session, if the session was successful, or if you are using manual evaluation logic, Link will return a `public_token` that you can exchange for an `access_token`. You can then proceed to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and/or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) , as described in the main [Auth integration process](https://plaid.com/docs/auth/index.html.md#auth-integration-process) .
6.  If the session was unsuccessful, Link will fall back to either an error screen or to a micro-deposit flow, depending on which options you selected in the Account Verification pane.

#### Understanding verification status and name score 

Your business logic will be based on the results of the verification status and the name score.

##### Verification status 

The possible values and most common causes for [verification\_status](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-status) for an Item going through the Database Auth flow are:

`database_insights_pass`: Plaid was able to match the account and routing number provided to an existing Item on the Plaid network and has high confidence that the account exists. The account is not known to be closed or frozen.

`database_insights_pass_with_caution`: Plaid was unable to match the account and routing number provided to an existing Item on the Plaid network, but the routing number is valid and the account number matches Plaid's known rules for account number formatting at the associated financial institution.

`database_insights_fail`: The routing number is not recognized, or the account number does not appear to match the formatting rules at the associated financial institution, or Plaid has received data indicating the account is closed or frozen.

In addition to the common causes above, additional risk factors may impact `verification_status` results.

Balance is not compatible with Items verified via Database Auth. If you need to check for potential ACH return risk for items verified via Database Auth, you must use Signal.

###### Understanding the pass with caution verification status 

Because `database_insights_pass_with_caution` is a common Database Insights result, how you choose to handle it is important.

In a typical test scenario, accepting only `pass` results reduced administrative return rates by by over 80%, while accepting both `pass` and `pass_with_caution` reduced administrative return rates by approximately 50%. Note that results will vary based on your own user base and use case and are not guarantees.

If you do not want to accept `database_insights_pass_with_caution`, you can configure Link to use a [Fallback flow](https://plaid.com/docs/auth/coverage/database-auth/index.html.md#fallback-flows) .

Signal and Identity Match are only compatible with Database Auth Items whose verification status is `database_insights_pass`. If you need to use Signal to check for non-administrative ACH return risk (e.g. R01 "insufficient funds" returns), or need to check for account takeover fraud using Identity Match, you should not accept the `database_insights_pass_with_caution` status.

##### Name match score 

The possible values for the name match score range from 0-100. In general, you should require a name match of at least 70 to effectively protect against account takeover attacks.

###### Example of how to interpret name match score 

| Range | Meaning | Example |
| --- | --- | --- |
| 100 | Exact match | Andrew Smith, Andrew Smith |
| 85-99 | Strong match, likely spelling error, nickname, or a missing middle name, prefix or suffix | Andrew Smith, Andrew Simth |
| 70-84 | Possible match, likely alias or nickname and spelling error | Andrew Smith, Andy Simth |
| 50-69 | Unlikely match, likely relative | Andrew Smith, Betty Smith |
| 0-49 | Unlikely match | Andrew Smith, Ray Charles |

##### Using your own evaluation logic (advanced) 

If you selected "For any Database Auth result, complete Link", you must write your own code for handling the results of the Database Auth verification.

To get the results, call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and examine the `verification_status`, `verification_insights`, and `verification_name` fields. Based on the values in these fields, you will make a decision on whether to accept the account data as verified, take additional risk mitigation steps, or reject the account data as unverified.

The `verification_insights` object will contain more detailed analysis showing exactly which checks passed or failed to result in the given `verification_status`. It will also contain the `name_score`.

For more details on the `verification_insights` values, see the [API Reference](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-insights) .

When using your own evaluation logic, you can fallback only to Automated Micro-deposits, and not to Instant Micro-deposits or Same-Day Micro-deposits.

When using other flows, customers using a [processor partner](https://plaid.com/docs/auth/partnerships/index.html.md) do not typically need to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , and can directly call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) instead. However, if you are using Database Auth with a processor partner and using your own evaluation logic, you must call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and check the value of the `verification_status` and/or `verification_insights` fields before passing a processor token to the partner.

##### Fallback flows 

If Database Auth fails, you can configure fallback to [Instant Micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) , [Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) , or [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) via the Account Verification Dashboard.

#### Testing Database Auth in Sandbox 

For test credentials that can be used to test Database Insights in the Sandbox environment, see [Testing Database Auth](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-auth-or-database-insights) .

---


# Auth - Database Insights and Match (legacy) | Plaid Docs

Database Insights and Match (legacy) 
=====================================

#### Evaluate a manually entered account using Plaid network data  

(An image of "Payment method selection page showing bank options with search. Car details, insurance info, and payment summary are displayed.")

The Database Insights end-user flow with Embedded Institution Search enabled.

#### Overview 

Database Insights and Database Match have been replaced with Database Auth in the US. The documentation provided here is for the use of customers maintaining support of existing legacy Database Insights and Database Match integrations, or building integrations for Canada.

Database Insights (legacy) can increase conversion by providing instant account verification without requiring users to link a bank account via credentials. End users choosing the manual Database Insights path will not be required to log in to their financial institution and instead can enter their account and routing number manually.

Database Insights verifies account and routing numbers by checking the information provided against Plaid's known account numbers, leveraging Plaid's database of over 200 million verified accounts. If no match is found, Plaid will check the account number format against known usages by the institution associated with the given routing number. Database Insights will provide a verification status of 'pass', 'pass with caution', or 'fail' and a set of attributes that contributed to that status, such as whether a match was found or whether Plaid fell back to checking account number formats.

Database Insights does not verify that the user has access to the bank account and Database Insights does also not fully guarantee that the account exists, especially in a 'pass with caution' scenario. For these reasons, Database Insights should only be enabled where there is a low risk of fraud or ACH returns. Examples of use cases where Database Insights may be appropriate include bill payment, rent collection, business to business payments, or subscription payments.

Approximately 30% of Items verified by Database Insights can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . For more details, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and [Signal](https://plaid.com/docs/signal/index.html.md) . All Items verified with Database Insights are also compatible with account ownership identity verification via [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) .

Database Insights and [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) are both designed to increase adoption of ACH payment methods and are frequently used together. Database Insights is also fully compatible with the standard, non-Embedded Institution Search Link flow.

##### Database Insights flow 

1.  Starting on a page in your app, the user clicks an action that opens Plaid Link.
2.  Inside of Plaid Link, the user selects an option to enter the manual verification flow and provides their account and routing number.
3.  Once the user has submitted their information, Link closes and returns a `public_token` within the `onSuccess` callback.
4.  Call `/item/token/exchange` to exchange the `public_token` for an `access_token`, then call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to obtain the account numbers and the verification results.
5.  Based on the values of the `verification_status` and `verification_insights` fields returned by [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , make a decision whether to proceed with the account information for ACH or to reject the account information as unverified.

When using other flows, customers using a [processor partner](https://plaid.com/docs/auth/partnerships/index.html.md) do not typically need to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , and can directly call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) instead. However, if you are using Database Insights with a processor partner, you must call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and check the value of the `verification_status` and/or `verification_insights` fields before passing a processor token to the partner.

#### Implementation steps 

##### Create a link\_token 

Create a `link_token` with the following parameters:

*   The `products` array should include only `auth` or `transfer` as a product when using Database Insights. While in most cases additional products can be added to existing Plaid Items, Items created with Database Insights are an exception and cannot be used with any Plaid products other than Auth, Transfer, Signal, or Identity Match.

Approximately 30% of Items verified by Database Insights can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or Signal. For more details, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and [Signal](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) . If using Identity Match or Signal in this way, they should be added to the Item via the `required_if_supported_products`, `optional_products`, or `additional_consented_products` fields rather than the `products` array.

*   `country_codes` should be set to `['US']` or `['CA']`– Database Insights is currently only available in the United States or Canada.
*   The `auth` object should specify `"database_insights_enabled": true`.
*   (Optional) Within the `auth` object, specify `"auth_type_select_enabled": true` in order to enable [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) , which will surface the manual entry point for Database Insights on the default Link screen. If Auth Type Select is not enabled, credential-based flows will be the primary UI flow and the Database Insights entry point will only appear as a fallback, except when using [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) .

Database Insights cannot be used in the same session as Database Match, Same-Day Micro-deposits, or Instant Micro-deposits. If any of those flows are explicitly enabled in the `auth` object alongside Database Insights, an error will occur when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . If they are implicitly enabled due to account default settings, they will be overridden by enabling Database Insights.

```javascript
const request: LinkTokenCreateRequest = {
  user: { client_user_id: new Date().getTime().toString() },
  client_name: 'Plaid App',
  products: [Products.Auth],
  country_codes: [CountryCode.Us],
  webhook: 'https://webhook.sample.com',
  language: 'en',
  auth: {
    database_insights_enabled: true
  },
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Initialize Link with a link\_token 

After creating a `link_token` for the `auth` product, use it to initialize Plaid Link.

When the user successfully inputs their account and routing numbers, the `onSuccess()` callback function will return a `public_token`.

```javascript
const linkHandler = Plaid.create({
  // Fetch a link_token configured for 'auth' from your app server
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token and connected accounts to your app server
    $.post('/exchange_public_token', {
      publicToken: public_token,
      accounts: metadata.accounts,
    });


    metadata = {
      ...,
      link_session_id: String,
      institution: {
        name: null, // name is always null for Database Insights
        institution_id: null // institution_id is always null for Database Insights
      },
      accounts: [{
        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
        mask: '1234',
        name: null,
        type: 'depository',
        subtype: 'checking',
        verification_status: ''
      }]
    }
  },
  // ...
});


// Open Link on user-action
linkHandler.open();
```

##### Exchange the public token 

In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` received in the `onSuccess` callback to obtain an `access_token`. Persist the returned `access_token` and `item_id` in your database in relation to the user.

Select group for content switcher

Current librariesLegacy libraries

```javascript
// publicToken and accountID are sent from your app to your backend-server
const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';


// Obtain an access_token from the Link public_token
const response = await client
  .itemPublicTokenExchange({
    public_token: publicToken,
  })
  .catch((err) => {
    // handle error
  });
const accessToken = response.access_token;
```

```json
{
  "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "m8MDnv9okwxFNBV"
}
```

##### Fetch Auth data and verification results 

Next, we can retrieve Auth data, along with the results of the Database Insights verification check, by calling [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';


// Instantly fetch Auth numbers
const request: AuthGetRequest = {
  access_token: accessToken,
};
const response = await client.authGet(request).catch((err) => {
  // handle error
});
const numbers = response.numbers;
```

```json
{
  "numbers": {
    "ach": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "account": "9900009606",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [],
    "international": [],
    "bacs": []
  },
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": { Object },
      "mask": "0000",
      "name": null,
      "official_name": null,
      "verification_status": "database_insights_pass",
      "verification_insights": { 
        "network_status": {
          "has_numbers_match": true, 
          "is_numbers_match_verified": true,
        },
        "previous_returns": { 
          "previous_administrative_return": false,
        },
        "account_number_format": "valid", 
      },
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "item": { Object },
  "request_id": "m8MDnv9okwxFNBV"
}
```

#### Making a risk determination 

The results of the Database Insights verification can be found in the `verification_status` and `verification_insights` fields returned by [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . Based on the values in these fields, you will make a business decision on whether to accept the account numbers as verified, take additional risk mitigation steps, or reject the account numbers as unverified.

#### Testing Database Insights in Sandbox 

For test credentials that can be used to test Database Insights in the Sandbox environment, see [Testing Database Auth or Database Insights](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-auth-or-database-insights) .

#### Database Match 

Database Insights and Database Match have been replaced with Database Auth. The documentation provided here is for the use of customers maintaining existing legacy Database Insights and Database Match integrations.

[Database Match](https://plaid.com/docs/auth/coverage/database/index.html.md#database-match) enables instant manual account verification without the need for micro-deposits, instead relying on Plaid's database of known account numbers. When provided as an alternative to Same-Day Micro-deposits, Database Match can increase conversion, as the user may be able to verify instantly, without having to return to Plaid to verify their micro-deposit codes.

Database Match will present the user with the option to manually add a bank account in Link by providing their name, account number, and routing number. Plaid will then check this information against its network of over 200 million known bank accounts. Approximately 30% of user bank accounts can be verified via Database Match. If a match is not found, Database Match will fall back to routing the user to a manual micro-deposit flow, either Instant Micro-deposits or Same-Day Micro-deposits.

Database Match can be used to verify the validity of the bank account being linked, but it does not verify that the end user has access to the bank account. To mitigate account takeover risk with Database Match, it can be paired with [Identity Match](https://plaid.com/docs/identity/index.html.md) to verify the user's information, such as phone number and address, on the linked account.

##### Database Match flow 

1.  Starting on a page in your app, the user clicks an action that opens Plaid Link.
2.  Inside of Plaid Link, the user selects an option to enter the manual verification flow and provides their legal name, account and routing number.
3.  Plaid will confirm the account number, routing number, and name match a previously verified account.
4.  If a match is confirmed, Link closes with a `public_token` and a verification status of `database_matched`.
5.  If there is no match, the user will be prompted to enter the Instant or Same Day Micro-deposits flow.

When these steps are complete, you can call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to obtain an `access_token` for calling endpoints such as [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) .

##### Database Match implementation steps 

To enable Database Match, use the same settings as Same-Day Micro-deposits. You can then enable the feature in one of two ways:

*   When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , set `auth.database_match_enabled: true`.
*   [In the Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , enable Database Match.

Database Match cannot be used in the same session as [Database Insights](https://plaid.com/docs/auth/coverage/database/index.html.md) . If Database Insights is explicitly enabled in the `auth` object alongside Database Match, an error will occur when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

```javascript
const request: LinkTokenCreateRequest = {
  user: { client_user_id: new Date().getTime().toString() },
  client_name: 'Plaid App',
  products: [Products.Auth],
  country_codes: [CountryCode.Us],
  webhook: 'https://webhook.sample.com',
  language: 'en',
  auth: {
    database_match_enabled: true,
    same_day_microdeposits_enabled, true
  },
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

When calling [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , the returned object will have a `verification_status` value of `database_matched` as an indication that the user's data was verified through Database Match.

```json
{
  "numbers": {
    "ach": [
      {
        "account": "1111222233330000",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    ...
  },
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": { Object },
      "mask": "0000",
      "name": "Checking...0000",
      "official_name": null,
      "verification_status": "database_matched",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  ...
}
```

##### Testing Database Match in Sandbox 

For test credentials that can be used to test Database Match in the Sandbox environment, see [Testing Database Match](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-match) .

---


# Auth - Configuring entry points | Plaid Docs

Configuring Auth entry points 
==============================

#### Configure end users' options for verifying their account with Reroute to Credentials and Auth Type Select 

#### Default manual verification flow entry point 

When using the default flow, the **Link with account numbers** entry point will appear when the user does any of the following:

*   Encounters an error in the Link flow
*   Selects an institution whose connection health is poor
*   Attempts to close the Link modal without connecting an institution
*   Receives a "no results" message when searching for an institution
*   Scrolls to the bottom of the institution search results

To trigger this flow via the [Link demo](https://plaid.com/demo) specify **Auth** in the Product dropdown menu and then **Launch Demo**. Trigger empty search results (type in a search query like ‘xyz’) or the Exit Pane (by closing Link) and select **Link with account numbers**.

This entry point will direct the user to Database Auth, Instant Micro-deposits, or Same-Day Micro-deposits, depending on which fallback options you have enabled and on whether the institution supports Instant ACH.

You can change these entry points using the features Auth Type Select and Reroute to Credentials.

Auth Type Select adds a prompt for the end user to pick a manual Auth flow upfront, without hitting any of the triggers above.

Reroute to Credentials is the opposite: it guides or forces the end user away from manual Auth flows if Plaid detects that the end user's institution is supported with a non-manual flow.

#### Adding manual verification entry points with Auth Type Select 

(An image of "Plaid auth manual link flow, select bank link option: Instantly or Manually. Continue button visible at the bottom.")

Auth Type Select is a Link configuration that shows a pane upfront, enabling end users to actively choose between credential-based authentication and manual account authentication at the start of the Plaid Link flow.

To demo **Auth Type Select** via the [Plaid Link demo](https://plaid.com/demo) , specify **United States** and **Auth** in the Country and Product dropdown menu respectively. Toggle on Auth Type Select, then **Launch Demo**.

To enable Auth Type Select, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or, if not using the Dashboard Account Verification pane, set `auth.auth_type_select_enabled: true` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

(An image of "Embedded institution search with Auth Type Select enabled, showing bank options and payment plan selection for PetGuard insurance.")

Embedded Institution Search with Auth Type Select enabled

##### When to use Auth Type Select 

Auth Type Select is best for customers who expect that a substantial portion of their consumers would prefer to authenticate manually, and who prefer to maximize Auth coverage over other data products. Examples may include business account verification use cases where a high percentage of users are not expected to have access to credentials of a bank account.

Customers that see the greatest success with the Auth Type Select configuration have a substantial portion of users (over half, as a rule of thumb) who cannot or will not connect by logging into their bank, who have invested in fraud risk mitigations or have a low risk use case, and/or have very high intent users (such as users connecting a bank account to receive a payment).

Some customers observe an increase in conversion of verified Auth data with this configuration. However, this configuration reduces coverage of other products. When offered the manual option upfront, more users may choose to link manually. Users who opt to connect via micro-deposits can have lower conversion than Instant Auth because the flow requires more steps for a user, including potentially returning to Link the next day to verify micro-deposits. It may encourage users to connect via micro-deposits who would otherwise connect via credential-based Auth types (if the manual option was not available upfront).

This configuration is best for customers who want to maximize Auth coverage and can tolerate reduced coverage of other products like Balance and Identity.

#### Removing manual verification entry points with Reroute to Credentials 

Reroute to Credentials will prompt users to use a login-based verification flow if they attempt to use a manual verification flow with an institution where login-based flows are supported. [Optional Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#optional-reroute) (the default Link flow) provides a nudge to use a login-based flow, but will not block manual verification, whereas [Forced Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#forced-reroute) will block manual verification if login-based flows are available. Alternatively, you can [disable Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#no-reroute) entirely.

In some cases, when rerouting a user to a supported institution, Plaid may show a list of institutions instead of a single institution. This can occur when a financial institution has multiple different brands that share a common routing number.

##### Optional Reroute 

Optional Reroute to Credentials is the default flow. It is best for customers who would like to make a recommendation for the user to connect via credentials, but not block the user from proceeding with the Same Day Micro-deposits flow. This flow will provide a reminder to the user that the institution is supported, and detail the benefits of instant connection, while also leaving the manual verification option in place. To enable Optional Reroute, you do not need to take any action.

If you have disabled Optional Reroute (by enabling [Forced Reroute](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#forced-reroute) or [No Reroute](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#no-reroute) ), you can re-enable it by using the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or set `auth.reroute_to_credentials: "OPTIONAL"` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

| Single Institution Optional Reroute | Multiple Institution Optional Reroute |
| --- | --- |
| 
(An image of "Sign in to Gingham Bank via Plaid using routing number 12341234. Tap 'Continue' or 'Enter account number instead.'")

 | 

(An image of "Mobile screen with options to select a financial institution. Choices: Gingham Bank, Herringbone Treasury. Option to enter account number.")

 |

##### Forced Reroute 

Forced Reroute to Credentials is best for customers who would like to restrict the user to connect via credentials if the institution is supported on a credential-based flow and stop the user from proceeding with a manual flow. This flow is designed to block a user from connecting manually for institutions that are supported via credentials in high ACH risk use cases. To enable Forced Reroute, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or set `auth.reroute_to_credentials: "FORCED"` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

| Single Institution Forced Reroute | Multiple Institution Forced Reroute |
| --- | --- |
| 
(An image of "Sign in to Gingham Bank using Wonderwallet with routing number 12341234. Press 'Continue' to securely connect your account.")

 | 

(An image of "Select an institution based on routing number 12345678. Options: Gingham Bank, Herringbone Treasury. Sign in required.")

 |

##### No Reroute 

To completely disable Reroute to Credentials, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or set `auth.reroute_to_credentials: "OFF"` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

---


# Auth - Additional Auth flows | Plaid Docs

Additional verification flows 
==============================

#### Support Auth for more US financial institutions and users 

#### Overview 

Instant Auth covers approximately 95% of users' eligible bank accounts. For the remaining ~5%, or users who choose not to use instant credential verification, Plaid offers users the ability to verify their accounts through an optimized set of database validation and micro-deposit flows.

[Our video tutorial also provides a comprehensive guide to adding Auth using micro-deposits](https://www.youtube.com/watch?v=FlZ5nzlIq74)

The following flows are enabled in your app by default once you have integrated Auth:

*   [Instant Auth](https://plaid.com/docs/auth/coverage/instant/index.html.md) : User enters their credentials and is authenticated immediately. This is the default flow.
*   [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) (US only): User enters their credentials, account number, and routing number. Plaid matches user input against masked values and authenticates immediately.

To increase conversion, you can enable the following additional Auth flows:

*   [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) (US only): User enters their credentials, account number, and routing number. Plaid makes a micro-deposit and automatically verifies the deposit in as little as one to two business days.
*   [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) (US only): User enters account and routing numbers. Plaid attempts to match this data against known-good account and routing numbers recognized on the Plaid network.
*   [Instant Micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) (US only): User enters account and routing numbers. Plaid makes a RTP or FedNow micro-deposit and the user manually verifies the code in as little as 5 seconds.
*   [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) (US only): User enters account and routing numbers. Plaid makes a Same Day ACH micro-deposit and the user manually verifies the code in as little as one business day.

To see each of these flows in action, check out the [Auth workflows demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100) .

##### Auth flow method comparison chart 

| Method | Best for | Verification timeframe | Requires additional integration work |
| --- | --- | --- | --- |
| [Instant Auth](https://plaid.com/docs/auth/coverage/instant/index.html.md) | All risk profiles | Instant | No (enabled by default) |
| [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) | All risk profiles | Instant | No (enabled by default) |
| [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) | All risk profiles | 1-2 business days | No, but requires "pending verification" UX state in app |
| [Instant Micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) | Low and medium risk profiles | Instant | No |
| [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) | Low and medium risk profiles | 1-2 business days, plus wait for user interaction | Yes, and requires "pending verification" UX state in app |
| [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) | Low and medium risk profiles | Instant | No, unless used in advanced configuration mode |

Accounts verified via Database Auth, Instant Micro-deposits, or Same-Day Micro-deposits do not have active data connections with a financial institution. These accounts and their associated Items can only be used with Auth and Transfer, not with any other Plaid products (such as Balance or Transactions), with the partial exception of [Identity Match](https://plaid.com/docs/identity/index.html.md#using-identity-match-with-micro-deposit-or-database-items) and [Signal](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) .

Because of this limitation, accounts verified via these flows may be more vulnerable to fraud or return risk. Consider your level of risk exposure and current anti-fraud measures before enabling these methods. For more details, see [Anti-fraud best practices](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) .

#### Entry points 

To learn more about when Plaid presents Database Auth, Instant Micro-deposits, or Same-Day Micro-deposits as options, and to customize the Link user experience around these flows, see [Configuring entry points](https://plaid.com/docs/auth/coverage/flow-options/index.html.md) .

#### Integration instructions 

Most additional Auth flows can be enabled in the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) with no additional integration work, as long as the following requirements are met:

*   The `country_codes` array in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is set to `["US"]`. Additional Auth flows are not available if other countries are selected.
*   The `products` array does not contain any products other than `auth` or `transfer`. Any other products you want to use must be configured in the `additional_consented_products`, `required_if_supported_products`, or `optional_products` arrays and will be used on a best-effort basis.

[Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) requires additional integration work, as you will need to present a Link UI where the end user can verify the micro-deposit description. For more details, see [Same-Day micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) .

[Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) , if used in the advanced mode where fallback rules are not configured in the Dashboard, requires additional integration work. For more details, see [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) .

(An image of "Alt text: 'Account Verification Dashboard with settings for instant verification methods, additional methods toggle, and micro-deposit options.'")

Example of some configuration options available in the Account Verification Dashboard

#### Institution coverage 

To see which Auth flows a given institution supports, you can call [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) with [options.include\_auth\_metadata](https://plaid.com/docs/api/institutions/index.html.md#institutions-get-request-options-include-auth-metadata) set to `true`. The results will be returned in the [auth\_metadata.supported\_methods object](https://plaid.com/docs/api/institutions/index.html.md#institutions-get-response-institutions-auth-metadata-supported-methods) in the response. Alternatively, you can see this information on the [Institution Status page](https://dashboard.plaid.com/activity/status) in the Plaid Dashboard. The Same Day Micro-deposits and Database Auth flows will not appear in these results, as they do not depend on institution capabilities and are available at all institutions.

---


# Auth - Instant Auth, Instant Match, & Instant Micro-deposits | Plaid Docs

Instant Auth, Instant Match, and Instant Micro-Deposits 
========================================================

#### Learn how to authenticate your users instantly 

#### Instant Auth 

Instant Auth supports more than 6,200 financial institutions with credential-based login. Instant Auth is the default Auth flow and does not require extra configuration steps if Auth is already configured in your app. For clarity and completeness, the section below explains how to configure Instant Auth.

The user signs in to their financial institution

(An image of "The user signs in to their financial institution")

(An image of "They select the account(s) to share with your application")

(An image of "And the account is verified")

You can try out the Instant Auth flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=3) . See more details in our [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-instant-match) .

##### Configure & Create a link\_token 

Create a `link_token` with the following parameters:

*   `products` array containing `auth` – If you are using only `auth` and no other products, `auth` must be specified in the Products array. Other products (such as `identity`) may be specified as well. If you are using multiple products, `auth` is not required to be specified in the products array, but including it is recommended for the best user experience.

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Initialize Link with a link\_token 

After creating a `link_token` for the `auth` product, use it to initialize Plaid Link.

When the user inputs their username and password for the financial institution, the `onSuccess()` callback function will return a `public_token`.

```javascript
Plaid.create({
  // Fetch a link_token configured for 'auth' from your app server
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token and accounts to your app server
    $.post('/exchange_public_token', {
      publicToken: public_token,
      accounts: metadata.accounts,
    });
  },
});
```

##### Exchange the public\_token and fetch Auth data 

In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` received in the `onSuccess` callback to obtain an `access_token`. Persist the returned `access_token` and `item_id` in your database in relation to the user. You will use the `access_token` when making requests to the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';


try {
  // Obtain an access_token from the Link public_token
  const tokenResponse = await client.itemPublicTokenExchange({
      public_token: publicToken}),
  const accessToken = tokenResponse.access_token;


  // Instantly fetch Auth numbers
  const request: AuthGetRequest = {
    access_token: accessToken,
  };
  const response = await plaidClient.authGet(request);
  const numbers = response.numbers;
} catch (err) {
  // handle error
}
```

Check out the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) API reference documentation to see the full Auth request and response schema.

```json
{
  "numbers": {
    "ach": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "account": "9900009606",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [],
    "international": [],
    "bacs": []
  },
  "accounts": [{ Object }],
  "item": { Object },
  "request_id": "m8MDnv9okwxFNBV"
}
```

#### Instant Match 

Instant Match is available for approximately 800 U.S. additional financial institutions where Instant Auth is not available. Instant Match is enabled automatically for Auth customers and is automatically provided at supported institutions as a fallback experience when Instant Auth is not available. When using Instant Match, Plaid Link will prompt your user to enter their account number and routing number for a depository account. Plaid will then verify the last four digits of the user-provided account number against the account mask retrieved from the financial institution.

The user signs in to their financial institution

(An image of "The user signs in to their financial institution")

(An image of "They select the account(s) to share with your application")

(An image of "They verify their bank's routing number...")

(An image of "...and their account number.")

(An image of "If those numbers match the accounts masks that Plaid has retrieved, the account is verified")

You can try out the Instant Match flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=4) . See more details in our [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-instant-match) .

When using the Instant Match flow, the user can verify only a single account. Even if the Account Select properties allow selecting all or multiple accounts, the ability to select multiple depository accounts for Auth will be disabled in Link if the institution is using the Instant Match flow.

##### Configuring in Link 

Instant Match will be enabled automatically if you configure the `link_token` with the following parameters:

*   add `"auth"` to `products` array
*   `country_codes` set to `['US']` (adding any other countries to the array will disable Instant Match)

Optionally, you can disable Instant Match on a per-session basis via the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, by setting `"auth.instant_match_enabled": false` in the request body. If you would like to disable Instant Match automatically for all Link sessions, contact your Account Manager or file a support ticket via the Dashboard.

```javascript
const request: LinkTokenCreateRequest = {
  user: { client_user_id: new Date().getTime().toString() },
  client_name: 'Plaid App',
  products: [Products.Auth],
  country_codes: [CountryCode.Us],
  language: 'en',
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Handling Link events 

For a user who goes through the Instant Match flow, the `TRANSITION_VIEW (view_name = NUMBERS)` event will occur after `SUBMIT_CREDENTIALS`, and in the `onSuccess` callback the `verification_status` will be `null` because the user would have been verified instantly.

```bash
OPEN (view_name = CONSENT)
TRANSITION_VIEW view_name = SELECT_INSTITUTION)
SEARCH_INSTITUTION
SELECT_INSTITUTION
TRANSITION_VIEW (view_name = CREDENTIAL)
SUBMIT_CREDENTIALS
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = MFA, mfa_type = code)
SUBMIT_MFA (mfa_type = code)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = SELECT_ACCOUNT)
TRANSITION_VIEW (view_name = NUMBERS)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess (verification_status: null)
```

#### Instant Micro-deposits 

Instant Micro-deposits is the Plaid product term for our ability to authenticate any bank account in the US that is supported by RTP or FedNow. For over 80 Plaid-supported banks, Instant Micro-deposits is the fastest and highest-converting form of Auth support available. If both Instant Micro-deposits and Same Day Micro-deposits are enabled, any user who attempts a micro-deposit with one of the over 400 eligible RTP or FedNow routing numbers will automatically experience the Instant Micro-deposits flow and be able to verify instantly.

##### Instant Micro-deposit flow 

The user opens Plaid Link.

(An image of "The user opens Plaid Link.")

(An image of "They select their institution.")

(An image of "They enter their account information...")

(An image of "...legal name...")

(An image of "...and the account type.")

(An image of "The user authorizes Plaid to make a deposit, and the deposit is made immediately.")

(An image of "The user is then prompted to enter the code associated with the deposit.")

(An image of "If the code matches the one that Plaid generated with the deposit description, the user's account is verified.")

1.  Starting on a page in your app, the user clicks an action that opens Plaid Link.
2.  Inside of Plaid Link, the user enters the micro-deposit initiation flow and provides their legal name, account and routing number.
3.  Plaid sends a micro-deposit to the user's account that will post within 5 seconds, and directs the user to log into their bank account to obtain the code from the micro-deposit description.
4.  The user enters the code from the micro-deposit description into Plaid Link.
5.  Upon success, Link closes with a `public_token` and a `metadata` account status of `manually_verified`.

Plaid will not reverse the $0.01 micro-deposit credit.

When these steps are done, your user's Auth data is verified and ready to fetch.

You can try out the Instant Micro-deposits flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=7) .

##### Configuring in Link 

Instant Micro-deposits will be enabled if you configure the `link_token` with the following parameters:

*   Set the `products` array to `["auth"]`. While in most cases additional products can be added to existing Plaid Items, Items created for micro-deposit verification are an exception and cannot be used with any Plaid products other than Auth or Transfer.

Approximately 30% of Items verified by Instant micro-deposits can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . For more details on using Identity Match with these Items, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) .

*   `country_codes` set to `['US']` (adding any other countries to the array will disable Instant Micro-deposits)
*   `auth.instant_microdeposits_enabled` set to `true`. For Plaid teams created prior to November 2023 this setting is not required; for newer teams, it must be manually configured.

Optionally, you can disable Instant Match on a per-session basis via the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, by setting `"auth.instant_microdeposits_enabled": false` in the request body. If you would like to disable Instant Match automatically for all Link sessions, contact your Account Manager or file a support ticket via the Dashboard.

##### Entering the Instant Micro-deposit flow 

Your user will enter the Instant Micro-deposit flow in the following scenarios:

*   The user selects an eligible institution that is not enabled for Instant Auth, Instant Match, or Automated Micro-deposits.
*   The Link session has [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) enabled and the user enters an eligible routing number during the Same Day Micro-deposits flow. In this case, the session will be "upgraded" to use Instant Micro-deposits rather than Same-Day Micro-deposits.

###### Instant Micro-deposit events 

When a user goes through the Instant micro-deposits flow, the session will have the `TRANSITION_VIEW` (`view_name = NUMBERS`) event and a `TRANSITION_VIEW` (`view_name = INSTANT_MICRODEPOSIT_AUTHORIZED`) event after the user authorizes Plaid to send a micro-deposit to the submitted account and routing number. In the `onSuccess` callback the `verification_status` will be `manually_verified` since, unlike Same Day Micro-deposits, Instant Micro-deposits will resolve to either a success or fail state within a single Link session.

##### Testing the Instant Micro-deposit flow 

For credentials that can be used to test Instant Micro-deposits in Sandbox, see [Auth testing flows](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-instant-micro-deposits) .

#### Automated Micro-deposits 

Integrate the automated micro-deposit flow

[View guide](https://plaid.com/docs/auth/coverage/automated/index.html.md)

#### Same Day Micro-deposits 

Integrate the manual micro-deposit flow

[View guide](https://plaid.com/docs/auth/coverage/same-day/index.html.md)

#### Testing in Sandbox 

Learn how to test each Auth flow in the Sandbox

[View guide](https://plaid.com/docs/auth/coverage/testing/index.html.md)

---


# Auth - Micro-deposit Events | Plaid Docs

Micro-deposit events 
=====================

#### Learn how to use Bank Transfers webhooks to receive micro-deposit status updates 

#### Overview 

If you are using the optional [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) verification flow for Auth and want to receive updates on the state of your micro-deposit transfers, you can enable webhooks for Bank Transfer events that notify you of transfer status updates for Plaid-initiated transfers within the ACH network.

#### Bank Transfers webhooks 

To enable Bank Transfers webhooks, add your endpoint on the [account webhooks](https://dashboard.plaid.com/developers/webhooks) page of the dashboard. You will need to have received production approval for Auth before being able to add an endpoint.

Bank Transfers webhooks are not part of Plaid's [Transfer](https://plaid.com/docs/transfer/index.html.md) product. All Auth customers have access to Bank Transfer webhooks; it is not required to sign up for Plaid Transfer to use these webhooks.

To confirm that your endpoint has been correctly configured, you can trigger a test webhook via [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) . You should receive the payload body specified below.

```json
{
  "webhook_type": "BANK_TRANSFERS",
  "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE"
}
```

Once you have enabled Bank Transfers webhooks, the [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) endpoint can be called to discover new ACH events. To know when you should call this endpoint, listen for the [BANK\_TRANSFERS\_EVENTS\_UPDATE](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfers_events_update) webhook. You will receive a Bank Transfers webhook any time you have posted or returned ACH micro-deposit events available. You can also search or filter micro-deposit events using the [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) endpoint.

Bank Transfers webhooks and the Bank Transfers endpoint will reflect any micro-deposit sent by Plaid, including both Same Day Micro-deposits and Automated Micro-deposits, if enabled. Bank Transfers webhooks and endpoints will only reflect data about ACH events initiated through Plaid. They do not reflect other ACH activity on a linked account.

#### Event types 

Once your user successfully completes the micro-deposit Link flow, you will receive an `account_id` in the success callback. Bank Transfers events also contain an `account_id`, which you should use to connect events to the corresponding user.

##### Pending 

A pending event type means that we have a record of the micro-deposit in our systems, but it has not yet been sent. You may assume that micro-deposits are in a pending state once you [exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) the corresponding Item’s public token for an access token. Note that Plaid does not send webhooks for new pending events, but you will still see pending events in event sync responses.

```json
{
  "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9",
  "bank_transfer_amount": "0.01",
  "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8",
  "bank_transfer_iso_currency_code": "USD",
  "bank_transfer_type": "credit",
  "direction": "outbound",
  "event_id": 5,
  "event_type": "pending",
  "failure_reason": null,
  "origination_account_id": null,
  "receiver_details": null,
  "timestamp": "2021-03-22T18:52:02Z"
}
```

###### Recommended action 

No action needed

##### Posted 

For successful micro-deposit transfers, `posted` events are the terminal event type, and no more events will be issued. Note that the end user may not receive the micro-deposit until several banking hours after the `posted` event. In addition, a `posted` event does not guarantee that the micro-deposit was successful; if the micro-deposit fails, a `reversed` event will eventually occur some time after the `posted` event.

```json
{
  "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9",
  "bank_transfer_amount": "0.01",
  "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8",
  "bank_transfer_iso_currency_code": "USD",
  "bank_transfer_type": "credit",
  "direction": "outbound",
  "event_id": 5,
  "event_type": "posted",
  "failure_reason": null,
  "origination_account_id": null,
  "receiver_details": null,
  "timestamp": "2021-03-22T18:52:02Z"
}
```

###### Recommended Action 

If the micro-deposit succeeds, all posted transfers will land in the end user’s account by 8:30am EST on the following banking day.

After the micro-deposit settlement time, Plaid recommends sending the end user an alert (through SMS, email, or push notification) to verify the micro-deposit amounts.

If you have enabled both Same Day and Automated micro-deposits, then before notifying the user, you should first confirm that the event corresponds to a Same Day micro-deposit by checking that the verification status is `pending_manual_verification` (and not `pending_automatic_verification`, which would correspond to an Automated Micro-deposit). Because Plaid handles Automated Micro-deposits without user interaction, it is not necessary to prompt the user during the Automatic Micro-deposit flow.

If you have not already stored the verification status, you can obtain it by calling [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) .

##### Reversed 

A `reversed` event indicates that a micro-deposit attempt has failed. Reversed events will contain an [ACH return code](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) that indicates why the micro-deposit failed.

```json
{
  "account_id": "bV8WNn73rLI5Ln1MmdErsDn9jv7w37uGMaQvP",
  "bank_transfer_amount": "0.01",
  "bank_transfer_id": "826712b2-c707-cf98-5ba9-13bd3cc2b2f0",
  "bank_transfer_iso_currency_code": "USD",
  "bank_transfer_type": "credit",
  "direction": "outbound",
  "event_id": 5,
  "event_type": "reversed",
  "failure_reason": {
    "ach_return_code": "R03",
    "description": "No account or unable to locate account"
  },
  "origination_account_id": null,
  "receiver_details": null,
  "timestamp": "2021-03-25T21:35:47Z"
}
```

###### Recommended Action 

Contact the user with a notification that authentication has failed. Once they return to your application, restart the Link flow to begin another authentication attempt.

---


# Auth - Anti-fraud best practices | Plaid Docs

Anti-fraud best practices 
==========================

#### Optimally configure manual entry verification flows to reduce fraud 

Plaid provides a suite of fraud prevention products that assist your application in catching bad actors and ACH returns. You can verify the source of funds with [Identity](https://plaid.com/docs/identity/index.html.md) , confirm the real-time [Balance](https://plaid.com/docs/balance/index.html.md) prior to a transfer, and leverage our machine learning model [Signal](https://plaid.com/docs/signal/index.html.md) to prevent returns and release funds earlier. These features are fully compatible with accounts connected via Instant Auth, Instant Match, and Automated Micro-deposits.

However, if an account is connected via a manual entry method such as Same Day Micro-deposits, Instant Micro-deposits, or Database Auth, these features are not always available and could increase the likelihood that you experience fraud and ACH returns. Following the recommendations below can help mitigate these risks.

##### Use Identity Match, Signal, and/or Identity Document Upload 

Approximately 30% of Items created with manual entry methods (including 100% of Items created by Database Auth that have a `database_insights_pass` verification status) are supported by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , which allows you to determine the likelihood that the user's identity details, such as name and address, on file with their financial institution match identity information held by you. For more details on this feature, see [Identity](https://plaid.com/docs/identity/index.html.md#identity-match) .

The same Items that are supported by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) are also supported by Signal. Signal can assess the return risk of a transaction based on machine learning analysis and alert you to high-risk transactions. For more details, see [Signal](https://plaid.com/docs/signal/index.html.md) .

[Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) verifies account owner identity based on bank statements, and is compatible with Items that don't support [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) . After creating the Item, you can use update mode to send the user through a Link session where they will be asked to upload a bank statement. Plaid will then analyze this statement for an account number match and will parse identity data from the statement. With the optional Fraud Risk feature, you can also check the uploaded statement for signs of fraud. For more details, see [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) .

##### Adjust a user’s Link experience based on their risk profile 

In order to reduce fraud upstream on your application, you can use [Plaid Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) to verify a government ID or match with a selfie of the document holder.

If your application does not have an identity verification solution or Plaid Link is not gated from the general public with fraud prevention and user verification checks in place, we do not recommend adopting manual entry verification flows as it may introduce an unnecessary fraud vector onto your platform.

If you identify a user to be riskier, consider disabling manual entry verification flows for those users.

Another option for riskier users is to leave manual entry verification flows enabled, but enable [Reroute to Credentials in Forced mode](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#forced-reroute) , which will only allow the user to link via manual entry verification flows when using a routing number not supported by other authentication methods.

You may also consider changing your user’s experience with your service based on their connection method. For example, if a user connected via a manual entry verification flow, you may consider enforcing a lower transfer threshold than for users where it was possible to verify identity and increasing hold times on those funds.

---


# Auth - Same Day Micro-deposits | Plaid Docs

Same Day Micro-deposits 
========================

#### Learn how to authenticate your users with a manually verified micro-deposit 

### Overview 

Same Day Micro-deposits can be used to authenticate any bank account in the US, but especially for the ~2,000 institutions that don't support Instant Auth, Instant Match, or Automated Micro-deposit verification. Plaid will make a deposit that will post within one business day (using Same Day ACH, which is roughly two days faster than the standard micro-deposit experience of two to three days). Users are instructed to manually verify the code in the transaction description deposited in the account.

#### The Same Day Micro-deposit flow 

The user clicks an action that opens Plaid Link.

(An image of "The user clicks an action that opens Plaid Link.")

(An image of "They choose to connect by entering account numbers manually.")

(An image of "The user enters their routing number...")

(An image of "...account number...")

(An image of "...full name...")

(An image of "...selects an account type...")

(An image of "...and authorizes the transfer.")

(An image of "The user enters their phone number to be notified when the transfer has arrived.")

(An image of "The user is told to come back in a few days.")

(An image of "A day or two later, the user recieves an SMS notification that the deposit has arrived.")

(An image of "After getting the code from their bank account, they return to Plaid to verify the code.")

(An image of "And the account is verified")

A user connects their financial institution using the following connection flow:

1.  Starting on a page in your app, the user clicks an action that opens Plaid Link with the correct Auth [configuration](https://plaid.com/docs/auth/coverage/same-day/index.html.md#create-a-link_token) .
2.  Inside of Plaid Link, the user enters the micro-deposit initiation flow and provides their legal name, account and routing number.
3.  Upon [successful authentication](https://plaid.com/docs/auth/coverage/same-day/index.html.md#exchange-the-public-token) , Link closes with a `public_token` and a `metadata` account status of `pending_manual_verification`.
4.  Behind the scenes, Plaid sends a micro-deposit to the user's account that will post within one to two business days.
5.  After one to two days, the user is prompted to verify the code in the transaction description in their account, by [opening Link with a generated link\_token](https://plaid.com/docs/auth/coverage/same-day/index.html.md#prompt-user-to-verify-micro-deposit-code-in-link) .

Plaid will not reverse the $0.01 micro-deposit credit.

When these steps are done, your user's Auth data is verified and [ready to fetch](https://plaid.com/docs/auth/coverage/same-day/index.html.md#fetch-auth-data) .

##### Demoing the flow in Link 

You can try out the Same Day Micro-deposits flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=8) . For more details, see the [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) .

#### Implementation steps 

##### Enable Same Day micro-deposits 

Enable Same Day micro-deposits via the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) . Alternatively, you can also enable this flow by setting the `auth.same_day_microdeposits_enabled: true` parameter when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

##### Create a link\_token 

Create a `link_token` with the following parameters:

*   `products` array should include only `auth` or `transfer` as a product when using same-day manual micro-deposit verification. While in most cases additional products can be added to existing Plaid Items, Items created for Same Day manual micro-deposit verification are an exception and cannot be used with any Plaid products other than Auth or Transfer.

Approximately 30% of Items verified by Same Day micro-deposits can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . If using Identity Match or Signal in this way, they should be added to the Item via the `required_if_supported_products`, `optional_products`, or `additional_consented_products` fields rather than the `products` array. For more details, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and [Signal](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) . All Items verified by Same Day micro-deposits are also compatible with statement-based verification via [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) .

*   `country_codes` set to `['US']` – Micro-deposit verification is currently only available in the United States.

##### Initialize Link with a link\_token 

After creating a `link_token` for the `auth` product, use it to initialize Plaid Link.

When the user successfully inputs their account and routing numbers, the `onSuccess()` callback function (or the equivalent field in [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) , if using the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration method) will return a `public_token`, with `verification_status` equal to `'pending_manual_verification'`.

```javascript
const linkHandler = Plaid.create({
  // Fetch a link_token configured for 'auth' from your app server
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token and connected accounts to your app server
    $.post('/exchange_public_token', {
      publicToken: public_token,
      accounts: metadata.accounts,
    });


    metadata = {
      ...,
      link_session_id: String,
      institution: {
        name: null,          // name is always null for Same Day Micro-deposits
        institution_id: null // institution_id is always null for Same Day Micro-deposits
      },
      accounts: [{
        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
        mask: '1234',
        name: "Checking...1234",
        type: 'depository',
        subtype: 'checking',
        verification_status: 'pending_manual_verification'
      }]
    }
  },
  // ...
});


// Open Link on user-action
linkHandler.open();
```

##### Display a "pending" status in your app 

Because Same Day verification usually takes one business day to complete, we recommend displaying a UI in your app that communicates to a user that verification is currently pending.

You can use the `verification_status` key returned in the `onSuccess` `metadata.accounts` object once Plaid Link closes successfully.

```javascript
verification_status: 'pending_manual_verification';
```

You can also [fetch the verification\_status](https://plaid.com/docs/auth/coverage/same-day/index.html.md#check-the-account-verification-status-optional) for an Item's account via the Plaid API, to obtain the latest account status.

##### Exchange the public token 

In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` to obtain an `access_token`.

When using same-day micro-deposit verification, only one account can be associated with each access token. If you want to allow a user to link multiple accounts at the same institution using same-day micro-deposits, you will need to create a new Link flow and generate a separate access token for each account.

To test your integration outside of Production, see [Testing Same Day Micro-deposits in Sandbox](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
// publicToken and accountID are sent from your app to your backend-server
const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';


// Obtain an access_token from the Link public_token
const response = await client
  .itemPublicTokenExchange({
    public_token: publicToken,
  })
  .catch((err) => {
    // handle error
  });
const accessToken = response.access_token;
```

```json
{
  "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "m8MDnv9okwxFNBV"
}
```

##### Check the account verification status (optional) 

In some cases you may want to implement logic in your app to display the `verification_status` of an Item that is pending manual verification. The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) API endpoint allows you to query this information.

To be notified via webhook when Plaid has sent the micro-deposit to your end user, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
// Fetch the accountID and accessToken from your database
const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
const request: AccountsGetRequest = {
  access_token: accessToken,
};
const response = await client.accountsGet(request).catch((err) => {
  // handle error
});
const account = response.accounts.find((a) => a.account_id === accountID);
const verificationStatus = account.verification_status;
```

```json
{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": { Object },
      "mask": "0000",
      "name": "Checking...0000",
      "official_name": null,
      "type": "depository",
      "subtype": "checking",
      "verification_status":
        "pending_manual_verification" |
        "manually_verified" |
        "verification_failed",
    },
    ...
  ],
  "item": { Object },
  "request_id": String
}
```

##### Prompt user to verify micro-deposit code in Link 

After one to two business days, the micro-deposit sent to the user's account is expected to be posted. To securely verify a Same Day Micro-deposits account, your user needs to come back into Link to verify the code in the transaction description.

When the micro-deposit posts to your end user's bank account, the transaction description will be written with the format:

```bash
#XXX  ACCTVERIFY
```

The `#` will be followed with the three letter code required for verification. The `<clientName>` is defined by the value of the `client_name` parameter that was used to create the `link_token` that initialized Link. Due to network requirements, the `client_name` will be truncated to the first 11 characters and `ACCTVERIFY` will be added to signify the deposit is for account verification.

Users with business or corporate accounts that have ACH debit blocks enabled on their account may need to authorize Plaid's Company / Tax ID, `1460820571`, to avoid any issues with linking their accounts.

To optimize conversion, we strongly recommend sending your user a notification (e.g. email, SMS, push notification) prompting them to come back into your app and verify the micro-deposit code. To be notified via webhook when Plaid has sent the micro-deposit to your end user, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) .

(An image of "Plaid Instant Match process: Enter 3-letter code from deposit, confirmation screen, success message linking to Wonderwallet.")

Verification of Same Day Micro-deposits is performed in two steps:

1.  In your backend server, create a new `link_token` from the associated `access_token` for the given user.
2.  Pass the generated `link_token` into your client-side app, using the `token` parameter in the Link configuration. This will automatically trigger the micro-deposit verification flow in Link.

##### Create a new link\_token from a persistent access\_token 

Generate a `link_token` for verifying micro-deposits by passing the user's associated `access_token` to the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) API endpoint. Note that the `products` field should not be set because the micro-deposits verification flow does not change the products associated with the given `access_token`.

Select group for content switcher

Current librariesLegacy libraries

```javascript
// Using Express
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    language: 'en',
    webhook: 'https://webhook.sample.com',
    country_codes: [CountryCode.Us],
    access_token: 'ENTER_YOUR_ACCESS_TOKEN',
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Initialize Link with the generated link\_token 

In your client-side app, pass the generated `link_token` into the Link `token` parameter. Link will automatically detect that Same Day verification is required for the Item and will open directly into the verification flow (see the image above).

In Link, the user will be prompted to log in to their personal banking portal to confirm the code in the micro-deposit transaction description. Upon successful entry of the code, the `onSuccess` callback will be fired, with an updated `verification_status: 'manually_verified'`. The verification code will be case-insensitive.

There is no time limit for the user to verify the deposit. A user has three attempts to enter the code correctly, after which the Item will be permanently locked for security reasons. See [INCORRECT\_DEPOSIT\_VERIFICATION](https://plaid.com/docs/errors/invalid-input/index.html.md#incorrect_deposit_verification) and [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) for errors that may occur during the micro-deposit initiation and verification flow.

```javascript
const linkHandler = Plaid.create({
  token: await fetchLinkTokenForMicrodepositsVerification(),
  onSuccess: (public_token, metadata) => {
    metadata = {
      accounts: [{
        ...,
        verification_status: 'manually_verified',
      }],
    };
  },
  // ...
});


// Open Link to verify micro-deposit amounts
linkHandler.open();
```

An Item's `access_token` does not change when verifying micro-deposits, so there is no need to repeat the exchange token process.

##### Fetch Auth data 

Finally, we can retrieve Auth data once the user has manually verified their account through Same Day Micro-deposits:

Select group for content switcher

Current librariesLegacy libraries

```javascript
const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';


// Instantly fetch Auth numbers
const request: AuthGetRequest = {
  access_token: accessToken,
};
const response = await client.authGet(request).catch((err) => {
  // handle error
});
const numbers = response.numbers;
```

```json
{
  "numbers": {
    "ach": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "account": "1111222233330000",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [],
    "international": [],
    "bacs": []
  },
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": { Object },
      "mask": "0000",
      "name": "Checking ...0000",
      "official_name": null,
      "verification_status": "manually_verified",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "item": { Object },
  "request_id": "m8MDnv9okwxFNBV"
}
```

Check out the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) API reference documentation to see the full Auth request and response schema.

#### Using Text Message Verification 

Text Message Verification is an alternative verification method for the Same Day Micro-deposit flow. With Text Message Verification, Plaid will send your user a one-time SMS message, directing them to a Plaid-hosted website where they can complete the micro-deposit verification process. When the user is done verifying their micro-deposit code, you will receive a [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook, telling you that the user has completed the process and that it is now safe to retrieve Auth information.

Text Message Verification can and should be used alongside the usual verification flow of prompting your user to verify their code inside your app through Link. The user may choose not to receive an SMS message from Plaid, or they might simply ignore the message, so it is important for your app to still provide a way for your user to complete the process.

##### Implementation steps 

Text Message Verification is enabled by default as long as Same Day Micro-deposits have been enabled. To opt out of Text Message Verification, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) to disable it, or, if not using the Account Verification Dashboard, set `auth.sms_microdeposits_verification_enabled: false` in your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

1.  When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , make sure you have specified a URL for your webhook receiver, so you can receive the [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook.
    
2.  Listen for the [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook.
    
    When the user completes the verification process, Plaid will send a [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook to the webhook receiver URL that you specified earlier. When you receive this webhook, review the value of the `status` field.
    
    ```json
    {
      "webhook_type": "AUTH",
      "webhook_code": "SMS_MICRODEPOSITS_VERIFICATION",
      "status": "MANUALLY_VERIFIED",
      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "environment": "sandbox"
    }
    ```
    
    A value of `MANUALLY_VERIFIED` indicates that the user successfully entered the micro-deposit code and has verified their account information. You can now retrieve Auth information on behalf of this user, and you should remove any pending in-app messages asking the user to complete the verification process.
    
    If you re-open Link and ask the user to verify their code after they have already verified it using Text Message Verification, Link will close immediately and fire the `onSuccess` callback. So even if you don't act on this webhook, your application will continue to function normally.
    
    A `status` field of `VERIFICATION_FAILED` indicates that the user failed the verification process. Verification cannot be retried once this status has been triggered; you will need to create a new Item.
    

##### User experience 

When the user goes through the Same Day Micro-deposit flow in Link, they will be prompted to enter their phone number. After the micro-deposit has been placed in their account, Plaid will contact the user via SMS with a URL pointing to a Plaid-hosted page where the user can complete the verification process. The text message itself will contain the following message:

```bash
Plaid: On behalf of [client_name], a $0.01 deposit was sent to your account ending in 1234. Verify this deposit here: https://hosted.plaid.com/link/lp1234. Then, return to [client_name] to complete your account setup.
```

Currently, the text message is only provided in English and will not be localized according to your Link customization settings.

##### Testing text message verification 

Text message verification cannot be tested in the Sandbox environment. Text messages will only be sent in Production.

#### Same Day Micro-deposit flow configuration options 

In addition to the default flow, Same Day Micro-deposits has several optional flow settings you can enable.

To expose more users to the Same Day micro-deposit flow, you can enable [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) , or to limit users' exposure to the flow, you can enable [Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#removing-manual-verification-entry-points-with-reroute-to-credentials) .

To provide an alternative flow that allows users to skip micro-deposit verification and instead relies on recognizing a known bank account within the Plaid network, you can enable [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) .

The setting that is best for you will depend on your use case, your risk exposure, and which other Plaid products you use. Learn more about how to optimize your configuration and manage risk under [best practices](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) .

Same Day Micro-deposit flow options are configured on a Link customization level (if using the Account Verification Dashboard) or on a Link token level (if configuring the options directly in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call). This enables you to decide which sessions are enabled for which flows; for example, you can enable different flows based on users' risk profiles.

#### Handling Link events 

When a user goes through the Same Day micro-deposits flow, the session will have the `TRANSITION_VIEW (view_name = NUMBERS)` event and a `TRANSITION_VIEW` (`view_name = SAME_DAY_MICRODEPOSIT_AUTHORIZED`) event after the user authorizes Plaid to send a micro-deposit to the submitted account and routing number. In the `onSuccess` callback the `verification_status` will be `pending_manual_verification` because the user will have to return to Link to verify their micro-deposit at a later Link session.

```bash
OPEN (view_name = CONSENT)
TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
SEARCH_INSTITUTION
TRANSITION_VIEW (view_name = NUMBERS)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess (verification_status: pending_manual_verification)
```

When a user goes through the Same Day micro-deposits flow with Reroute to Credentials, you will additionally see `TRANSITION_VIEW (view_name = NUMBERS_SELECT_INSTITUTION)` with `view_variant = SINGLE_INSTITUTION` or `view_variant = MULTI_INSTITUTION`.

```bash
OPEN (view_name = CONSENT)
TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
SEARCH_INSTITUTION
TRANSITION_VIEW (view_name = NUMBERS)
TRANSITION_VIEW (view_name = NUMBERS_SELECT_INSTITUTION, view_variant = SINGLE_INSTITUTION)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess (verification_status: pending_manual_verification)
```

When a user goes through the Same Day micro-deposits flow with the Auth Type Select configuration, you will additionally see `TRANSITION_VIEW (view_name = SELECT_AUTH_TYPE)` and also `SELECT_AUTH_TYPE (selection = flow_type_manual)`

```bash
OPEN (view_name = CONSENT)
TRANSITION_VIEW (view_name = SELECT_AUTH_TYPE)
SELECT_AUTH_TYPE (selection = flow_type_manual)
TRANSITION_VIEW (view_name = NUMBERS)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess (verification_status: pending_manual_verification)
```

#### Testing in Sandbox 

Learn how to test each Auth flow in the Sandbox

[View guide](https://plaid.com/docs/auth/coverage/testing/index.html.md)

#### Manual verification flow best practices 

Minimize fraud by following best practices

[View guide](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md)

#### Micro-deposit events 

Learn how to use webhooks to receive micro-deposit status updates

[View guide](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md)

---


# Auth - Test in Sandbox | Plaid Docs

Testing Auth flows 
===================

#### Testing Instant Match and micro-deposit flows 

#### Sandbox configuration 

To test in the [Sandbox environment](https://plaid.com/docs/sandbox/index.html.md) , you need to set the Link configuration environment to `"sandbox"`:

```javascript
Plaid.create({
  // ...
  env: 'sandbox',
});
```

You will also want to direct any backend API requests to the sandbox URL:

```undefined
https://sandbox.plaid.com
```

#### Testing Instant Match 

##### Test credentials 

| Sandbox input | Successful credentials | Erroneous credentials |
| --- | --- | --- |
| Institution Name | Houndstooth Bank (`ins_109512`) | –– |
| Username | `user_good` | –– |
| Password | `pass_good` | –– |
| Account Selection | `Plaid Savings (****1111)` | –– |
| Routing number | `021000021` | Any other routing number |
| Account number | `1111222233331111` | Any other account number |

##### Entering the Link flow 

*   Search for “Houndstooth Bank” in Link.
*   Use the input data in the table above to simulate the desired outcome.

#### Testing Instant Micro-deposits 

You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/demo/) .

| Sandbox input | Successful credentials | Erroneous credentials |
| --- | --- | --- |
| Institution name | Windowpane Bank (`ins_135858`) | –– |
| Routing number | `333333334` | Any other value (if testing upgrade path) |
| Account number | `1111222233330000` | –– |
| Deposit code | `ABC` | Any other value |

##### Entering the primary Link flow 

*   Search for "Windowpane Bank" in Link.
*   When prompted, use the input data in the table above to simulate the desired outcome.
*   For all other fields, you can use any values.

##### Testing the upgrade path from Same Day Micro-deposits to Instant Micro-deposits 

*   If you have enabled Same Day Micro-deposits, enter gibberish into the search bar to ensure no institutions will be found, then click on Link with account numbers.
*   If you have configured Same Day Micro-deposits with Auth Type Select, choose "Manually" from the menu.
*   When prompted, enter the input data in the table above. For all other fields, you can use any values.
*   Note that, unlike the primary Instant Micro-deposits flow, the routing and account number entries will be on separate panes.

#### Testing Database Match 

You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/demo/) .

##### Test credentials 

To simulate a `database_matched` result:

| Sandbox input | Credentials |
| --- | --- |
| Routing number | `110000000` |
| Account number | `1111222233331111` |
| Name | `John Smith` |

Any other input will simulate no match and proceed with Same Day Micro-deposits, e.g.:

| Sandbox input | Credentials |
| --- | --- |
| Routing number | `110000000` |
| Account number | `1111222233332222` |
| Name | `John Smith` |

##### Entering the Link flow 

*   If you have enabled Database Match, enter gibberish into the search bar to ensure no institutions will be found, then click on Link with account numbers.
*   If you have configured Database Match with Auth Type Select, choose "Manually" from the menu.
*   Use the input data in the table above to simulate different outcomes.

#### Testing Database Auth or Database Insights 

You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/demo/) .

##### Test credentials (US-based sessions) 

To simulate a `database_insights_pass` result:

| Sandbox input | Credentials |
| --- | --- |
| Routing number | Any routing number (e.g. `110000000`) |
| Account number | `1111222233331111` |

To simulate a `database_insights_pass_with_caution` result:

| Sandbox input | Credentials |
| --- | --- |
| Routing number | Any routing number (e.g. `110000000`) |
| Account number | `1111222233333333` |

Any other account number will simulate a `database_insights_fail` result, e.g.:

| Sandbox input | Credentials |
| --- | --- |
| Routing number | Any routing number (e.g. `110000000`) |
| Account number | `1111222233332222` |

##### Test credentials (CA-based sessions) 

To simulate a `database_insights_pass` result:

| Sandbox input | Credentials |
| --- | --- |
| Institution number | `110` |
| Branch number | `11111` |
| Account number | `11223311` |

To simulate a `database_insights_pass_with_caution` result:

| Sandbox input | Credentials |
| --- | --- |
| Institution number | `110` |
| Branch number | `11111` |
| Account number | `11223333` |

Any other input will simulate a `database_insights_fail` result, e.g.:

| Sandbox input | Credentials |
| --- | --- |
| Institution number | `110` |
| Branch number | `11111` |
| Account number | `11223322` |

##### Entering the Link flow 

*   If you have configured Database Auth or Database Insights with Auth Type Select, choose "Manually" from the menu.
*   If you have configured Database Auth or Database Insights with Embedded Search, choose "Connect Manually".
*   If you have enabled Database Auth or Database Insights without either of the above options, enter gibberish into the search bar to ensure no institutions will be found, then click on "Link with account numbers".
*   Use input data from the table above to simulate various outcomes.

#### Testing Automated Micro-deposits 

You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/demo/) .

##### Test credentials 

| Sandbox input | Successful credentials | Erroneous credentials |
| --- | --- | --- |
| Institution Name | Houndstooth Bank (`ins_109512`) | –– |
| Username | `user_good` | –– |
| Password | `microdeposits_good` | –– |
| Account Selection | `Plaid Checking (****0000)` | –– |
| Routing number | `021000021` | Any other routing number |
| Account number | `1111222233330000` | Any other account number |

##### Entering the Link flow 

*   Search for “Houndstooth Bank” in Link.
*   Use the input data in the table above to simulate the desired outcome.

The micro-deposit verification will automatically succeed after twenty-four hours. To test a failed micro-deposit, or to skip the twenty-four hour waiting period, use the [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) endpoint to manually control the Item's micro-deposit verification status.

#### Testing Same Day Micro-deposits 

You can also test this flow with no code by using the [Link Demo](https://plaid.com/demo/) .

##### Test credentials 

| Sandbox input | Successful credentials | Erroneous credentials |
| --- | --- | --- |
| Routing number | `110000000` | –– |
| Account number | `1111222233330000` | –– |
| Deposit code | `ABC` | Any other value |

##### Initiating micro-deposits in Link 

*   If you have configured Same Day Micro-deposits with Auth Type Select, choose "Manually" from the menu
*   If you have enabled Same Day Micro-deposits without Auto Type Select, enter gibberish into the search bar to ensure no institutions will be found, then click on "Link with account numbers".
*   Use the input data in the table above to simulate the desired outcome.

##### Verifying micro-deposits in Link 

*   Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) with your `public_token` from the Link session in previous step to receive an `access_token`.
*   Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and provide the `access_token` from the previous step to receive a `link_token`.
*   Open Link with your `link_token`.
*   In the deposit code field, enter `ABC`

#### Testing micro-deposit events 

Micro-deposits that are generated in Sandbox will never be posted by default. In order to generate a posted event that you can see when you query [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) , you can use the [/sandbox/bank\_transfer/simulate](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transfersimulate) endpoint.

Simulating a posted event in Sandbox does not generate a webhook. You will need to call [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) each time you want a webhook to be published for testing.

#### Testing Identity Match with Same Day micro-deposit Items 

| Sandbox input | Successful credentials | Erroneous credentials |
| --- | --- | --- |
| Routing number | `011401533` | `110000000` |
| Account number | `1111222233330000` | `1111222233330000` |
| Deposit code | `ABC` | `ABC` |

*   Complete the Same Day Micro-deposits flow as detailed above
*   Call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) using any variation of data in order to test the matching algorithm
*   The identity data of the test user is as follows:

| Field | Sandbox identity |
| --- | --- |
| Name | Alberta Bobbeth Charleson |
| Email | [accountholder0@example.com](https://plaid.commailto:accountholder0@example.com) |
| Phone | 1112223333 |
| Street | 2992 Cameron Road |
| City | Malakoff |
| Region | NY |
| Country | US |
| Postal Code | 14236 |

---


# Auth - Introduction to Auth | Plaid Docs

Introduction to Auth  
======================

#### Instantly retrieve account information to set up pay-by-bank payments via ACH and more 

(An image of "Link an account")

(An image of "Fetch account info")

(An image of "Initiate a payment")

Get started with Auth

[API Reference](https://plaid.com/docs/api/products/auth/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/6786ccc5a048a5f1cf748cb5?zoom=100)

Auth allows you to request a user's checking, savings, or cash management account and routing number, making it easy for you to initiate credits or debits via ACH, wire transfer, or equivalent international networks. Auth makes it easy for end users to fund an account with your app, cash out to their bank account, or make purchases via pay-by-bank.

Auth must be used with a payment processor to move money: either a [Plaid Partner](https://plaid.com/docs/auth/partnerships/index.html.md) or another third party. For more information, see [Using a Payments Service](https://plaid.com/docs/auth/index.html.md#using-a-payments-service) . For an all-in-one solution that includes payment processor functionality, see [Transfer](https://plaid.com/docs/transfer/index.html.md) (US-only). For more details, see [Auth vs. Transfer comparison](https://plaid.com/docs/payments/index.html.md#auth-and-transfer-comparison) .

Auth can only be used with debitable checking, savings, or cash management accounts. Credit-type accounts, including credit cards, cannot receive payments directly via electronic interbank transfers, and Auth data cannot be used to set up credit card payments. Auth can not be used to connect debit cards; instead, you can make a transfer directly from the user's bank account, saving you money over using the debit card network.

[Prefer to learn by watching? Get an overview of how Auth works in just 3 minutes!](https://www.youtube.com/watch?v=2ZsANOjVjIs)

Auth is commonly used in combination with other Plaid APIs that reduce risk and support compliance, such as [Balance](https://plaid.com/docs/balance/index.html.md) (to verify accounts have sufficient funds), [Signal](https://plaid.com/docs/signal/index.html.md) (to calculate the risk of ACH returns with ML-powered analysis), and [Identity](https://plaid.com/docs/identity/index.html.md) (to verify ownership information on the account).

For account funding use cases, see [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) for an end-to-end KYC compliance solution with optional AML capabilities.

#### Auth integration process 

Below is a high level overview of the Auth integration process. For a more detailed walkthrough, see [Add auth to your app](https://plaid.com/docs/auth/add-to-app/index.html.md) or (if applicable) the docs for the specific [partner](https://plaid.com/docs/auth/partnerships/index.html.md) you are using.

Embedded Link for pay-by-bank applications

If your use case involves the end user choosing between paying via a credit card and paying via a bank account, it is strongly recommended to use the [Embedded experience](https://plaid.com/docs/link/embedded-institution-search/index.html.md) for Link to increase uptake of pay-by-bank.

1.  Create a Link token by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `auth` in the `products` parameter.
2.  Initialize Link with the Link token from the previous step. For more details, see [Link](https://plaid.com/docs/link/index.html.md) .
    *   For Link configuration recommendations, see [Optimizing the Link UI for Auth](https://plaid.com/docs/auth/index.html.md#optimizing-the-link-ui-for-auth) .
3.  Once the user has successfully completed the Link flow, exchange the `public_token` for an `access_token`.
4.  If using a Plaid partner for payment processing, ensure the partner is enabled on your [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) , then call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) to obtain a token that you will provide to the partner to enable funds transfers. For more detailed instructions, including a full walkthrough, see [Auth payment partners](https://plaid.com/docs/auth/partnerships/index.html.md) .
5.  If not using a Plaid partner, call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to obtain the account and routing number, then provide these fields to your payment processing system.
6.  Listen for the [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) webhook. If you receive it, send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . If update mode is not completed for the Item within 7 days of webhook receipt, consent will expire, which may lead to the account and routing number becoming invalid, as described in the next step.
7.  Listen for the [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) and [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) webhooks. These webhooks indicate that you must send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to refresh consent. Attempting to use the account and routing number for transactions without successfully completing update mode may result in ACH returns.
    *   If the Item is at PNC, after sending the Item through update mode, you must _also_ call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) , as relevant to your use case, to get a new set of routing and account numbers. As a best practice, it is recommended you do this _every_ time you send a PNC Item through update mode when using Auth. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) .
8.  (Optional) Listen for the [AUTH: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#default_update) webhook. This webhook indicates that the routing and/or account number for an account on the Item has changed (this is very rare). Call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) on that Item, as applicable for your integration, and use only the new numbers or processor token.
9.  (Optional) To enable and configure additional Auth verification flows, such as micro-deposit verification or database verification, use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) . For demos and more information, see [Additional verification flows](https://plaid.com/docs/auth/coverage/index.html.md) .

#### Using a payments service 

Looking for bank-to-bank transfer capabilities and don't have a payment processor yet? Check out [Transfer](https://plaid.com/docs/transfer/index.html.md) (US only) for a money movement solution with built-in payment processing capabilities. See [Auth and Transfer comparison](https://plaid.com/docs/payments/index.html.md#auth-and-transfer-comparison) to learn more.

When using Auth, you will send Auth data to a payments service to initiate an interbank transfer; Plaid does not function as the payment processor. While Plaid is processor-agnostic and allows you to work with any partner you want, one easy way to make transfers is to work with a payments platform that partners with Plaid, such as Dwolla or Square. Working with these partners, you will not call the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint, so you will not obtain a user's bank account information. Instead, you will call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) to obtain a Plaid token that you will provide to the partner and that allows them to make these Plaid API calls as needed. For detailed instructions on how to set up Auth with a Plaid partner, as well as a list of supported funds transfer partners, see [Auth Partnerships](https://plaid.com/docs/auth/partnerships/index.html.md) .

If you choose to use a payments provider who is not a Plaid partner, you will need to obtain bank account numbers and codes using [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . Given the sensitive nature of this information, we recommend that you consult the [Open Finance Data Security Standard](https://ofdss.org/) for security best practices. We also recommend that you do not store account numbers. You can integrate with one of Plaid's [Data Security partners](https://plaid.com/partner-directory/) to process and share tokenized bank account numbers instead of raw bank account numbers. Contact your Account Manager to learn more about these partnerships.

#### Account Verification Dashboard 

Using the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) , you can customize the Auth flow to increase conversion, enabling features like micro-deposit-based verification and database verification for end users who cannot or do not want to log into their bank accounts. You can also customize when these features are presented to users. The Account Verification Dashboard also allows you to reduce account takeover fraud by incorporating [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) directly into the Link flow.

For more information on the Auth flows you can enable via the Account Verification Dashboard, see [Micro-deposit and database verification flows](https://plaid.com/docs/auth/coverage/index.html.md) .

You can also use the [Dashboard](https://dashboard.plaid.com/account-verification) to view the status of any completed, Auth-enabled Link session.

(An image of "Session status showing Link Session ID with identity match status and auth method in Account Verification Dashboard.")

The Dashboard [Account Verification analytics page](https://dashboard.plaid.com/account-verification/analytics) shows a breakdown of Auth conversion analytics by [connection method](https://plaid.com/docs/auth/coverage/index.html.md) .

(An image of "image of Account Verification analytics")

#### Optimizing the Link UI for Auth 

By default, only checking, savings, and cash management accounts will appear when using Auth, and institutions that do not support these accounts will not appear in the Institution Select pane.

The following Link configuration options are commonly used with Auth:

*   [Account select](https://plaid.com/docs/link/customization/index.html.md#account-select) : The "Account Select: Enabled for one account" setting configures the Link UI so that the end user may only select a single account. If you are not using this setting, you will need to build your own UI to let your end user select which linked account they want to use to send or receive funds.
*   [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) : This presentation mode shows the Link institution search screen embedded directly into your UI, before the end user has interacted with Link. Embedded Institution Search increases end user uptake of pay-by-bank payment methods and is strongly recommended when implementing Auth as part of a pay-by-bank use case where multiple different payment methods are supported.

#### Pay by bank optimization 

If you have a pay-by-bank use case, see [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for tips on how to reduce your transaction fees by increasing the uptake of customers choosing to pay by bank.

#### Tokenized account numbers 

Institutions that interface with Plaid via an OAuth portal may return a tokenized account number (TAN) in the Auth response. These TANs are standard account and routing numbers that can be utilized by any ACH processor, and will be reconciled by the issuing bank on settlement. Each app a user connects to will receive a unique TAN, rather than the user's exact account number. TANs allow either the end-user or the institution itself to more rigorously monitor and even sever a specific app's ability to transfer funds. These account numbers behave differently from regular account numbers in a number of important ways.

To determine if a tokenized account number is being used, use the `is_tokenized_account_number` field in the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) response. Currently, only Chase, PNC, and US Bank use tokenized account numbers.

Only the `numbers.ach.account` field can be set as a TAN (excluding brokerage or international specific numbers results). TANs are only valid for the ACH and RTP payment rails - they may not be used for wire transfers or physical checks. TANs may not be supported by your third-party fraud and account verification databases and vendors.

Institutions that use TANs do not always expose them to end users; to avoid confusion, in user-facing UIs, always display the account mask rather than the account number, as end users will not recognize the issued TAN.

If a user revokes access to their account (such as via the Chase Security center or [my.plaid.com](https://my.plaid.com/) ), the TAN will become invalid and any attempt to make a transfer using that TAN will fail with an R04 return code. To avoid returns, listen for the [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) and [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_account_revoked) webhooks and do not use an account number, processor token, or Stripe bank account token associated with an Item or account where access has been revoked. Instead, send the end user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to restore the Item and then call the Auth endpoint again.

At US Bank, TANs do not become invalid, even after Item deletion or revocation.

Because account numbers alone cannot reliably be used to uniquely identify TAN-enabled accounts across different Item instances, Plaid provides a [persistent\_account\_id](https://plaid.com/docs/api/accounts/index.html.md#accounts-get-response-accounts-persistent-account-id) field for this purpose. This field is only available at institutions that use TANs.

If a Chase [duplicate Item](https://plaid.com/docs/link/duplicate-items/index.html.md) is created, the old Item will be invalidated, but the TAN on the new Item will remain the same. The TAN will only change if the user revokes access.

If multiple Items in your app correspond to the same account (for example, in the case of a joint bank account with multiple owners), each Item will typically have a different TAN.

TANs will always be accompanied by a routing number. The TAN must be used with the routing number returned by the API. If used with a different routing number, even one associated with the same bank, the transfer may fail.

In Sandbox, the Auth product results will have the `is_tokenized_account_number` boolean set to true if the Chase (`ins_56`), PNC (`ins_13`), US Bank (`ins_127990`), or the Platypus OAuth Bank (`ins_127287`) `institution_id` is set in the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) request body or the respective FIs are selected from the Sandbox Link pane.

##### PNC TAN expiration 

At PNC, any Item initialized with Auth after October 2024 will have a [consent\_expiration\_time](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-item-consent-expiration-time) set to 1 year from the date that the user last provided consent, with the first expirations to occur in October 2025. When the Item's consent expires, the TAN will expire as well and cannot be used to make ACH transfers. This applies regardless of how you are accessing the account numbers: via [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , via the Transfer product, or via processor tokens.

You can renew consent on the Item by sending the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . If the Item has less than six months of valid consent remaining, the end user will automatically be asked to renew consent when entering the update mode flow. To override this behavior, set `update.reauthorization_enabled` to `true` or `false` during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call used to create the Link token for update mode.

If the Item's consent had already expired when you sent the Item through update mode, you must call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , `/processor/token/get`, or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) to obtain a new TAN after completing update mode, as the old TAN will not be re-activated.

In addition, if the user has multiple depository accounts at PNC, then when going through the OAuth portion of the update mode flow, it's possible that they may de-select the PNC account that they originally shared with you and select a different PNC account instead. If this happens, the TAN of the account they originally shared will be invalidated. For this reason, it is recommended to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , `/processor/token/get`, or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) _every_ time you send a PNC Item through update mode.

Note that there is no additional fee for these API calls, since Auth uses a one-time fee billing model; you are only charged for your first Auth call to each Item.

PNC TAN expiration does not apply to Items initialized with Auth prior to October 2024, as these Items use real account numbers rather than TANs.

#### Updates to Auth data 

Because routing and account numbers are inherently persistent, Plaid does not check for updates to Auth data for existing Items except in special circumstances, such as a bank changing its routing numbers due to a system change or merger. Plaid will also check for updated Auth data if a new user account is added to an Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) .

#### United States (ACH) Auth data 

The United States uses the Automated Clearing House (ACH) system for funds transfers, which uses account and routing numbers. Banks also have a second routing number, known as the wire transfer routing number. Wire transfers can be used to receive international payments and can be faster than ACH transfers, but often involve a fee. Plaid Auth can only provide wire transfer routing numbers for institutions in the US.

For a detailed, comprehensive guide to ACH transfers and payments, see Plaid's [Modern Guide to ACH](https://plaid.com/solutions/ACH-guide/) .

```json
"numbers": {
  "ach": [
    {
      "account": "1111222233330000",
      "account_id": "bWG9l1DNpdc8zDk3wBm9iMkW3p1mVWCVKVmJ6",
      "routing": "011401533",
      "wire_routing": "021000021"
    }
  ],
  "bacs": [],
  "eft": [],
  "international": []
}
```

#### Auth data for other countries 

##### Canada (EFT) 

In Canada, the routing number is in a different format than US routing numbers and broken into two pieces: the transit number (also known as the branch number), followed by the institution number. Canada uses Electronic Funds Transfer (EFT); [VoPay](https://plaid.com/docs/auth/partnerships/vopay/index.html.md) is a Plaid partner that can be used to process EFT transfers.

```json
"numbers": {
  "eft": [
    {
      "account": "111122220000",
      "account_id": "qVZ3Bwbo5wFmoVneZxMksBvN6vDad6idkndAB",
      "branch": "01533",
      "institution": "114"
    }
  ],
  ...
}
```

##### Europe (SEPA transfers) 

For funds transfers in Europe, also consider the [Payment Initiation API](https://plaid.com/docs/payment-initiation/index.html.md) , which allows end-to-end payments directly, without having to integrate an additional payment processor.

In the European Economic Area member states (which includes Euro zone nations, as well as the United Kingdom), institutions use a Bank Identifier Code (BIC), also known as a SWIFT code. Each bank account has an International Bank Account Number (IBAN), which is used along with the BIC for funds transfers. Many bank accounts also have internal, non-IBAN account numbers that cannot be used for funds transfers. The funds transfer system is known as the Shared European Payment Area (SEPA), and it supports SEPA credit transfer, SEPA instant credit transfer, and SEPA direct debit.

```json
"numbers": {
  "international": [
    {
      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "bic": "IE64BOFI90583812345678",
      "iban": "IE64BOFI90583812345678"
    }
    ...
  ]
}
```

##### United Kingdom (BACS) 

For funds transfers in the UK, also consider the [Payment Initiation API](https://plaid.com/docs/payment-initiation/index.html.md) , which allows end-to-end payments directly, without having to integrate an additional payment processor.

The UK uses the SEPA system as well as the Bankers Automated Clearing System (BACS). Payments within the BACS system cannot be made outside the UK and take several days to process. BACS payments are typically used for recurring direct debit payments, such as payroll. UK bank accounts will typically have both a BACS sort code and an IBAN and support both BACS transfers and SEPA transfers.

```json
"numbers": {
  "bacs": [
    {
      "account": "80000000",
      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "sort_code": "040004"
    }
  ],
  "international": [
    {
      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "bic": "MONZGB21XXX",
      "iban": "GB23MONZ04000480000000"
    }
  ]
  ...
}
```

#### Sample app code 

For a real-life example of an app that incorporates Auth, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L135) .

#### Testing Auth 

Plaid provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users) with test data for testing Auth in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) .

For details on testing Auth with more complex Auth flows such as micro-deposit-based Auth, first familiarize yourself with [Adding Institution Coverage](https://plaid.com/docs/auth/coverage/index.html.md) , then see [Test in Sandbox](https://plaid.com/docs/auth/coverage/testing/index.html.md) .

#### Auth pricing 

Auth is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

Now that you understand Auth, [add Auth to your app](https://plaid.com/docs/auth/add-to-app/index.html.md) , or see [Move Money with Auth partners](https://plaid.com/docs/auth/partnerships/index.html.md) to see specific instructions for configuring Auth with Plaid partners.

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Auth - Dwolla | Plaid Docs

Add Dwolla to your app 
=======================

#### Use Dwolla with Plaid Auth to send and receive payments 

(An image of "Plaid and Dwolla logos, side by side.")

  

Plaid and Dwolla have partnered to offer businesses an easier way to connect to the U.S. banking system. Plaid enables businesses to instantly authenticate a customer's bank account, giving them the ability to leverage the Dwolla API to connect to the ACH or RTP® networks for sending and receiving payments. Dwolla’s solution offers frictionless ACH or real-time payments payments for companies looking to automate their current payments process and scale their business.

With the Plaid + Dwolla integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid’s front-end module. Plaid’s mobile-friendly module handles input validation, error handling, and multi-factor authentication–providing a seamless onboarding experience to convert more users for your business.

As part of the integration, Dwolla customers can access Plaid’s full suite of APIs for clean, categorized transaction data, real-time balances, and more.

#### Getting started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/docs/link/index.html.md) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication.

Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH or RTP® transactions. From there, you'll receive a Plaid `access_token`, allowing you to leverage real-time balance checks and transaction data, and a Dwolla `processor_token`, which allows you to quickly and securely verify a bank funding source via [Dwolla's API](https://www.dwolla.com/?utm_campaign=Plaid-Documentation&utm_source=Plaid&utm_medium=Referral) without having to store any sensitive banking information. Utilizing Plaid + Dwolla enables a seamless workflow for sending and receiving payments.

#### Instructions 

##### Set up your Plaid and Dwolla accounts 

You'll need accounts at both Plaid and Dwolla in order to use the Plaid + Dwolla integration. You'll also need to be a Dwolla customer in order to add a bank funding source.

First, [sign up for a Dwolla account](https://accounts.dwolla.com/sign-up/pay-as-you-go?utm_campaign=Plaid-Documentation&utm_source=Plaid&utm_medium=Referral) if you don't already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup/dwolla) . Your account will be automatically enabled for integration access.

To verify that your Plaid account is enabled for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Dwolla to enable the integration.

Use the [Dwolla Sandbox](https://developers.dwolla.com/guides/sandbox-setup/) to test the Plaid + Dwolla integration for free.

##### Complete your Plaid application profile and company profile 

After connecting your Plaid and Dwolla accounts, you'll need to complete your Plaid [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. View the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) documentation for a full list of `link_token` configurations.

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Dwolla `processor_token`.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onLoad: function() {
          // The Link module finished loading.
      },
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has
        // successfully authenticated and selected an account to
        // use.
        //
        // When called, you will send the public_token and the selected accounts,
        // metadata.accounts, to your backend app server.


        sendDataToBackendServer({
           public_token: public_token,
           accounts: metadata.accounts
        });
      },
        console.log('Public Token: ' + public_token);
        console.log('Customer-selected account ID: ' + metadata.account_id);
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error
            // prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent
        // API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In order to avoid any confusion about which account your user wishes to use with Dwolla, it is recommended to set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account.

Once you have identified the account you will use, you will send the `account_id` property of the account to Plaid, along with the `access_token`, to create a Dwolla `processor_token`. You'll send this token to Dwolla and they will use it to securely retrieve account and routing numbers from Plaid.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
} = require('plaid');
// Change sandbox to production when you're ready to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: publicToken,
  });
  const accessToken = tokenResponse.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'dwolla',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.processor_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "[Unique request ID]"
}
```

##### Make a request to Dwolla 

Once you've obtained the `processor_token`, you'll then pass it to Dwolla as the value of the `plaidToken` request parameter, along with a funding source `name`, to create a funding source for a Dwolla Customer:

```bash
POST https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C/funding-sources
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY


{
  "plaidToken": "processor-sandbox-161c86dd-d470-47e9-a741-d381c2b2cb6f",
  "name": "Jane Doe’s Checking"
}


...


HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31
```

Once you’ve received a successful response from the Dwolla API, you’ll use the unique funding source URL to identify the Customer’s bank when [initiating ACH](https://docs.dwolla.com/#initiate-a-transfer?utm_campaign=Plaid-Documentation&utm_source=Plaid&utm_medium=Referral) or [RTP transfers](https://developers.dwolla.com/concepts/real-time-payments#real-time-payments?utm_campaign=Plaid-Documentation&utm_source=Landing-Page&utm_medium=Referral) .

##### Testing your Dwolla integration 

You can create Dwolla `processor_tokens` in Sandbox (sandbox.plaid.com, allows testing with simulated users) or Production (production.plaid.com, requires Dwolla Production credentials).

To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) when launching Link with a `link_token` created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`.

##### Get ready for production 

Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) .

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) .

For a tutorial walkthrough of creating a similar app with Dwolla support, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

#### Support and questions 

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth | Plaid Docs

Add Gainbridge to your app 
===========================

#### Instantly authenticate your customers' bank accounts to fund policies through Gainbridge's Bank Accounts API 

(An image of "Partnership Gainbridge logo")

  

#### Overview 

Plaid and Gainbridge have partnered together to integrate Plaid’s connectivity platform with Gainbridge’s digital investing platform. This integration will allow you to securely establish and verify your users’ bank accounts through Plaid, and safely transmit authenticated account information to Gainbridge for policy funding through ACH payments:

*   Instantly authenticate users’ bank accounts with Plaid Link (i.e. enhance user experience, reduce wait times for bank account verification with Microdeposits).
*   Securely share tokenized banking data to connect with Gainbridge’s Bank Accounts API, used to initiate ACH debits on your customer’s bank accounts to fund a Gainbridge policy.

#### Getting Started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Gainbridge account](https://enterprise.gainbridge.io/contact) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Gainbridge `processor_token`, which allows you to quickly and securely verify a bank funding source via [Gainbridge's API](https://enterprise.gainbridge.io/platform-overview) without having to store any sensitive banking information. Utilizing Plaid + Gainbridge enables a seamless workflow for connecting external financial accounts to Gainbridge.

#### Instructions 

##### Set up your accounts 

You'll need accounts at both Plaid and Gainbridge in order to use the Plaid + Gainbridge integration. You'll also need to enable your Plaid account for the Gainbridge integration.

First, you will need to work with the Gainbridge team to [sign up for a Gainbridge account](https://enterprise.gainbridge.io/contact) , if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) .

To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Gainbridge to enable the integration.

You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Gainbridge to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Gainbridge.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Gainbridge `processor_token`.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has successfully
        // authenticated and selected an account to use.
        //
        // When called, you will send the public_token and the selected accounts,
        // metadata.accounts, to your backend app server.
        sendDataToBackendServer({
           public_token: public_token,
           accounts: metadata.accounts
        });
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    // Link will automatically detect the institution ID
    // associated with the public token and present the
    // credential view to your user.
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Gainbridge, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account.

Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Gainbridge `processor_token`. You'll send this token to Gainbridge and they will use it to securely retrieve account details from Plaid.

You can create Gainbridge `processor_tokens` in both API environments:

*   Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users
*   Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Gainbridge Production credentials

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
} = require('plaid');


// Change sandbox to production when you're ready to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: publicToken,
  });
  const accessToken = tokenResponse.data.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'gainbridge',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.data.processor_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "m8MDnv9okwxFNBV"
}
```

For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) .

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135)

#### Launching to Production 

##### Test with Sandbox credentials 

To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`.

##### Get ready for production 

Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Gainbridge Production credentials prior to initiating live traffic in the Gainbridge API with Plaid.

##### Support and questions 

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth - Gusto | Plaid Docs

Add Gusto to your app 
======================

#### Build payroll with Gusto, then use Plaid Auth to instantly connect your customers’ bank accounts and run payroll faster 

(An image of "Partnership Gusto logo")

  

#### Overview 

Gusto and Plaid have partnered so your customers can quickly and easily configure company bank accounts for seamless, in-app payroll.

You shouldn’t compromise on payroll accuracy and compliance for your customers and their employees. With Gusto Embedded Payroll’s APIs, you can leverage the road-tested payroll engine and expertise of Gusto to build payroll capabilities directly into your platform.

This integration allows your customers to easily connect company bank accounts through Plaid’s Auth flow. A `processor_token` is a Plaid token used by Gusto to make API calls on your behalf. You will generate a `processor_token` on behalf of the customer and then pass that token to Gusto. The token allows Gusto to instantly retrieve bank account details, so you don’t need to store and protect sensitive bank information.

#### Getting Started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Gusto account](https://dev.gusto.com/accounts/sign_up) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Gusto `processor_token`, which allows you to quickly and securely verify a bank funding source via [Gusto's API](https://docs.gusto.com) without having to store any sensitive banking information. Utilizing Plaid + Gusto enables a seamless workflow for connecting external financial accounts to Gusto.

#### Instructions 

##### Set up your accounts 

You'll need accounts at both Plaid and Gusto in order to use the Plaid + Gusto integration. You'll also need to enable your Plaid account for the Gusto integration.

First, you will need to work with the Gusto team to [sign up for a Gusto account](https://dev.gusto.com/accounts/sign_up) , if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) .

To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Gusto to enable the integration.

You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Gusto to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Gusto.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Gusto `processor_token`.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has successfully
        // authenticated and selected an account to use.
        //
        // When called, you will send the public_token and the selected accounts,
        // metadata.accounts, to your backend app server.
        sendDataToBackendServer({
           public_token: public_token,
           accounts: metadata.accounts
        });
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    // Link will automatically detect the institution ID
    // associated with the public token and present the
    // credential view to your user.
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Gusto, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account.

Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Gusto `processor_token`. You'll send this token to Gusto and they will use it to securely retrieve account details from Plaid.

You can create Gusto `processor_tokens` in both API environments:

*   Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users
*   Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Gusto Production credentials

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
} = require('plaid');


// Change sandbox to production when you're ready to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: publicToken,
  });
  const accessToken = tokenResponse.data.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'gusto',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.data.processor_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "m8MDnv9okwxFNBV"
}
```

For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) .

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135)

#### Launching to Production 

##### Test with Sandbox credentials 

To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`.

##### Get ready for production 

Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Gusto Production credentials prior to initiating live traffic in the Gusto API with Plaid.

##### Support and questions 

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth - Money movement partnerships | Plaid Docs

Auth Payment Partners 
======================

#### Find payment providers who have partnered with Plaid to provide general purpose ACH money movement 

\=\*=\*=\*=

#### Overview 

Many Plaid developers choose to use a Plaid partner to move money with Auth. You will use Plaid Link initialized with the Auth product, but instead of using Plaid Auth endpoints, you will use endpoints from the payment platform, giving you access to payment functionality while freeing you from having to securely store sensitive bank account information.

The following is a list of payments platforms who have partnered with Plaid to provide ACH money movement via a special processor token, along with instructions on how to enable those integrations.

| Partner | Description |
| --- | --- |
| [Dwolla](https://plaid.com/docs/auth/partnerships/dwolla/index.html.md) | Instantly authenticate your customers' bank accounts for use with Dwolla's ACH API |
| [Square](https://plaid.com/docs/auth/partnerships/square/index.html.md) | Instantly authenticate your customers' bank accounts for use with the Square Web Payments SDK |
| [ACHQ](https://plaid.com/docs/auth/partnerships/achq/index.html.md) | Instantly authenticate your customers' bank accounts for use with ACHQ's ACH API |
| [Roll by ADP](https://plaid.com/docs/auth/partnerships/adp-roll/index.html.md) | Authenticate your customers’ bank accounts for secure payroll direct deposit support. |
| [Adyen](https://plaid.com/docs/auth/partnerships/adyen/index.html.md) | Validate bank accounts and reduce returns through an end-to-end pay-with-your-bank solution with Adyen |
| [Alpaca](https://plaid.com/docs/auth/partnerships/alpaca/index.html.md) | Use Alpaca with Plaid Auth to send and receive payments |
| [Ansa](https://plaid.com/docs/auth/partnerships/ansa/index.html.md) | Instantly authenticate your customers' bank accounts for use with the Ansa API to enable wallet funding over ACH |
| [Apex Fintech Solutions](https://plaid.com/docs/auth/partnerships/apex-clearing/index.html.md) | Instantly authenticate your investors’ bank accounts for use with Apex Fintech Solutions Cash API |
| [Astra](https://plaid.com/docs/auth/partnerships/astra/index.html.md) | Instantly authenticate your customer’s bank accounts for automated ACH transfers through the Astra platform |
| [Atomic](https://plaid.com/docs/auth/partnerships/atomic/index.html.md) | Instantly authenticate your customers' bank accounts to seamlessly fund investment accounts |
| [Bakkt](https://plaid.com/docs/auth/partnerships/bakkt/index.html.md) | Instantly authenticate your customer’s accounts to use with Bakkt Fiat Services API for ACH based money movement |
| [Bond](https://plaid.com/docs/auth/partnerships/bond/index.html.md) | Instantly authenticate your customers’ bank accounts for use with Bond’s ACH Transfers API |
| [Check](https://plaid.com/docs/auth/partnerships/check/index.html.md) | Check lets you embed payroll in your product and easily configure and authenticate direct deposit payments |
| [Checkbook](https://plaid.com/docs/auth/partnerships/checkbook/index.html.md) | Instantly authenticate your customers’ bank accounts for use with Checkbook’s payment solution -- including ACH, real-time payments, push to card, virtual cards, and checks |
| [Checkout.com](https://plaid.com/docs/auth/partnerships/checkout/index.html.md) | Instantly authenticate bank account details for use with Checkout.com’s Unified Payments API, and unlock unrivaled payment performance |
| [DriveWealth](https://plaid.com/docs/auth/partnerships/drivewealth/index.html.md) | Enable your customers to instantly and securely fund DriveWealth supported investment accounts by linking their bank account with Plaid |
| [Finix](https://plaid.com/docs/auth/partnerships/finix/index.html.md) | Instantly add customer bank accounts to Finix to accept and send payments with tokenized payment information. It’s fast, frictionless, and secure. |
| [Fortress Trust](https://plaid.com/docs/auth/partnerships/fortress-trust/index.html.md) | Instantly allow end customers to connect, verify and authorize funding to their Fortress Trust account from their external bank accounts |
| [Gainbridge](https://plaid.com/docs/auth/partnerships/gainbridge/index.html.md) | Instantly authenticate your customers' bank accounts to fund policies through Gainbridge's Bank Accounts API |
| [Galileo](https://plaid.com/docs/auth/partnerships/galileo/index.html.md) | Instantly authenticate your customers' bank accounts for account opening and funding |
| [Gusto](https://plaid.com/docs/auth/partnerships/gusto/index.html.md) | Build payroll with Gusto, then use Plaid Auth to instantly connect your customers’ bank accounts and run payroll faster |
| [Highnote](https://plaid.com/docs/auth/partnerships/highnote/index.html.md) | Instantly authenticate your customer’s bank accounts for use with the Highnote Platform to store account details, transfer funds, and make payments |
| [Lithic](https://plaid.com/docs/auth/partnerships/lithic/index.html.md) | Instant bank authentication for ACH payments and card loads |
| [Marqeta](https://plaid.com/docs/auth/partnerships/marqeta/index.html.md) | Integrate Plaid and Marqeta’s APIs to seamlessly authenticate your customer’s bank account prior to an ACH transfer |
| [Modern Treasury](https://plaid.com/docs/auth/partnerships/modern-treasury/index.html.md) | Instantly authenticate your customers' bank accounts for use with Modern Treasury's ACH API |
| [Moov](https://plaid.com/docs/auth/partnerships/moov/index.html.md) | Instantly authenticate your customers’ bank accounts to enable them to accept, store, and disburse funds with Moov |
| [Paynote](https://plaid.com/docs/auth/partnerships/paynote/index.html.md) | Enhance your checkout and reduce returns with Paynote ACH. Utilize Plaid’s verification and real-time balance checks to instantly debit and credit bank accounts. |
| [Riskified](https://plaid.com/docs/auth/partnerships/riskified/index.html.md) | Provide fraud screening and ACH payment guarantee |
| [Rize](https://plaid.com/docs/auth/partnerships/rize/index.html.md) | Use Plaid to instantly verify and connect your customers’ external bank accounts for use within the Rize Platform |
| [Sardine](https://plaid.com/docs/auth/partnerships/sardine/index.html.md) | Protect your users by using Sardine’s all-in-one fraud and compliance API |
| [ScribeUp](https://plaid.com/docs/auth/partnerships/scribeup/index.html.md) | Embed subscription management into your digital banking experience |
| [Sila Money](https://plaid.com/docs/auth/partnerships/sila-money/index.html.md) | Banking, Digital Wallets, and ACH Payments API for software teams |
| [Silicon Valley Bank](https://plaid.com/docs/auth/partnerships/svb/index.html.md) | Instantly authenticate your customers' bank accounts for use with Silicon Valley Bank's ACH API |
| [Solid](https://plaid.com/docs/auth/partnerships/solid/index.html.md) | Instantly authenticate external bank accounts for use with the Solid Platform |
| [Stake](https://plaid.com/docs/auth/partnerships/stake/index.html.md) | Instantly authenticate your resident bank accounts for use with the Stake Enterprise API. |
| [Straddle](https://plaid.com/docs/auth/partnerships/straddle/index.html.md) | Integrate Plaid with Straddle to deliver secure, identity-linked bank payments that settle quickly and feel as simple and reliable as using a debit card. |
| [Stripe](https://plaid.com/docs/auth/partnerships/stripe/index.html.md) | Instantly authenticate your customers' bank accounts for use with Stripe's ACH API |
| [TabaPay](https://plaid.com/docs/auth/partnerships/taba-pay/index.html.md) | Instantly process ACH/RTP/FedNow with TabaPay’s Unified API using your Plaid Token |
| [Treasury Prime](https://plaid.com/docs/auth/partnerships/treasury-prime/index.html.md) | Send payments and create counterparties with the Treasury Prime API |
| [Unit](https://plaid.com/docs/auth/partnerships/unit/index.html.md) | Instantly authenticate counterparties’ bank accounts for use with the Unit API |
| [VoPay](https://plaid.com/docs/auth/partnerships/vopay/index.html.md) | Eliminate inefficiencies of US and Canadian online bank account payments with VoPay’s EFT / ACH and Plaid |
| [Wedbush](https://plaid.com/docs/auth/partnerships/wedbush/index.html.md) | Plaid-linked bank accounts can be connected to fund or withdraw from accounts on the Wedbush Securities platform. |
| [Zero Hash](https://plaid.com/docs/auth/partnerships/zero-hash/index.html.md) | Use Zero Hash with Plaid Auth to embed bank account linking for ACH-funded crypto trades |

For more information, see the full list of partners in the [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) .

\=\*=\*=\*=

#### Global payments options 

Money movement via Plaid partners is only available for financial institutions within the US (with multiple providers above) and Canada (with [VoPay](https://plaid.com/docs/auth/partnerships/vopay/index.html.md) , [Modern Treasury](https://plaid.com/docs/auth/partnerships/modern-treasury/index.html.md) , or [Finix](https://plaid.com/docs/auth/partnerships/finix/index.html.md) ). In Europe, [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) provides an easy and secure way to transfer funds.

\=\*=\*=\*=

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) .

For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

---


# Auth - Stripe | Plaid Docs

Add Stripe to your app 
=======================

#### Use Stripe with Plaid Auth to send and receive payments 

(An image of "Plaid + Stripe logo image")

  

Plaid and Stripe have partnered to offer frictionless money transfers without the need to ever handle an account or routing number. Use [Plaid Link](https://plaid.com/docs/link/index.html.md) to instantly authenticate your customer's account and generate a Stripe [bank account token](https://plaid.comhttps://stripe.com/docs/api/index.html.md#create_bank_account_token) so that you can accept ACH payments via Stripe.

Plaid can be used with Stripe's [ACH Charges and Sources API](https://plaid.comhttps://stripe.com/docs/ach-deprecated/index.html.md) as well as with the newer Stripe [Payment Intents API](https://plaid.comhttps://stripe.com/docs/payments/payment-intents/index.html.md) . Note that Stripe has marked the Charges and Sources API as deprecated. However, the Charges and Sources API and Plaid integration are still both fully supported by both Plaid and Stripe. To use Plaid with the [Payment Intents API](https://plaid.comhttps://stripe.com/docs/payments/payment-intents/index.html.md) , you will need to contact Stripe to request a manual exception.

This guide is designed for those who already have developer accounts with both Stripe and Plaid. If that's not you, [Sign up for a Plaid Dashboard account](https://dashboard.plaid.com/signup) , then head over to the [Stripe docs](https://dashboard.stripe.com/register) to get a Stripe account.

The sample Plaid integration code used in the Stripe-hosted [Charges and Sources ACH documentation](https://plaid.comhttps://stripe.com/docs/ach-deprecated/index.html.md) demonstrates the use of a legacy version of the Plaid client libraries. For new customers, we recommend using the sample code within this guide for building your integration.

#### Getting Started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/docs/link/index.html.md) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication.

Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH transactions. From there, you'll receive a Plaid `access_token`, allowing you to leverage real-time balance checks and transaction data, and a Stripe `bank_account_token`, which allows you to move money via Stripe's ACH API without ever handling an account or routing number.

#### Instructions 

##### Set up your Plaid and Stripe accounts 

You'll need accounts at both Plaid and Stripe in order to use the Plaid Link + Stripe integration. You'll also need to connect your Plaid and Stripe accounts so that Plaid can facilitate the creation of bank account tokens on your behalf.

First, sign up for a Stripe account if you do not already have one and then verify that it is enabled for ACH access. To verify that your Stripe account is ACH enabled, head to the [Charges and Sources ACH Guide](https://plaid.comhttps://stripe.com/docs/ach-deprecated/index.html.md) when you are logged in to your Stripe account. If you see:

(An image of "Integrations page showing Stripe with an OFF status icon")

your account is not enabled. Click 'Accept Terms of Service' to enable your Stripe account for ACH. If you do not see the 'Accept Terms of Service' button, your Stripe account is already enabled for ACH access and you do not need to take any action.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup/stripe) . Your account will be automatically enabled for integration access.

To verify that your Plaid account is enabled for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If you see:

(An image of "Unlinked Stripe account")

your Plaid account is enabled for the integration but you have not connected your Stripe account.

Click the 'Connect With Stripe' button to connect your Plaid and Stripe accounts. This step is required so that Plaid can facilitate the creation of Stripe bank account tokens on your behalf.

Once your Stripe account is connected, you'll see:

(An image of "linked Stripe account")

Your Plaid account is now set up for the integration!

##### Complete your Plaid application profile and company profile 

After connecting your Stripe and Plaid accounts, you'll need to complete your Plaid [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of parameters, see the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) reference.

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Stripe bank account token.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onLoad: function() {
          // The Link module finished loading.
      },
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has
        // successfully authenticated and selected an account to
        // use.
        //
        // When called, you will send the public_token
        // and the data about which account to use
        // to your backend app server. In this example,
        // we assume "Account Select" is set to
        // "enabled for one account".
        //
        // sendDataToBackendServer({
        //   public_token: public_token,
        //   account_id: metadata.accounts[0].id
        // });
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error
            // prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent
        // API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In order to avoid any confusion about which account your user wishes to use with Stripe, it is recommended to set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one element.

Once you have identified the account you will use, you will call [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) , sending Plaid the `account_id` property of the account along with the `access_token` you obtained from [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . Plaid will create and return a Stripe [bank account token](https://plaid.comhttps://stripe.com/docs/api/index.html.md#create_bank_account_token) for this account, which can then be used to move money via Stripe's ACH API. The bank account token will be linked to the Stripe account you linked in your [Plaid Dashboard](https://dashboard.plaid.com/) .

Note that the Stripe bank account token is a one-time use token. To store bank account information for later use, you can use a Stripe [customer object](https://plaid.comhttps://stripe.com/docs/api/customers/object/index.html.md) and create an associated [bank account](https://plaid.comhttps://stripe.com/docs/api/customer_bank_accounts/create/index.html.md) from the token, or you can use a Stripe [Custom account](https://plaid.comhttps://stripe.com/docs/api/accounts/index.html.md) and create an associated [external bank account](https://plaid.comhttps://stripe.com/docs/api/external_account_bank_accounts/create/index.html.md) from the token. This bank account information should work indefinitely, unless the user's bank account information changes or they revoke Plaid's permissions to access their account (when using certain financial institutions). The Plaid `access_token`, on the other hand, does not expire and should be persisted securely.

Stripe bank account information cannot be modified once the bank account token has been created. If you ever need to change the bank account details used by Stripe for a specific customer, you should repeat this process from the beginning, including creating a `link_token`, sending the customer through the Link flow, generating a new bank account token, and creating a new customer object or Custom account.

Select group for content switcher

Current librariesLegacy libraries

```javascript
// Change sandbox to production when you're ready to go live!
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorStripeBankAccountTokenCreateRequest,
} = require('plaid');
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: publicToken,
  });
  const accessToken = tokenResponse.data.access_token;


  // Generate a bank account token
  const request: ProcessorStripeBankAccountTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
  };
  const stripeTokenResponse = await plaidClient.processorStripeBankAccountTokenCreate(
    request,
  );
  const bankAccountToken = stripeTokenResponse.data.stripe_bank_account_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",
  "request_id": "[Unique request ID]"
}
```

For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) .

Note: The `account_id` parameter is required if you wish to receive a Stripe bank account token.

##### Test with Sandbox credentials 

You can create Stripe bank account tokens in all three API environments:

*   Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users with Stripe's "test mode" API
*   Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live

Plaid's Sandbox API environment is compatible with Stripe's "test mode" API. To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) when launching Link with a `link_token` created in the Sandbox environment. The Stripe bank account token created in the Sandbox environment will always match the Stripe bank test account with account number 000123456789 and routing number 110000000, and with the Stripe account that is linked in the Plaid Dashboard.

Use Stripe's [ACH API](https://plaid.comhttps://stripe.com/docs/guides/ach/index.html.md) in test mode to create test transfers using the bank account tokens you retrieve from Plaid's Sandbox API environment.

Plaid's Sandbox is not compatible with the Stripe Sandbox environment. To test your Plaid - Stripe integration, you must use Stripe test mode, rather than Stripe Sandboxes.

When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`.

##### Get ready for production 

Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ), which allows you to test with Sandbox API credentials. To move to Production, request access from the [Dashboard](https://dashboard.plaid.com/settings/team/products) .

##### Next steps 

Once you're successfully retrieving Stripe `bank_account_token`s, you're ready to make ACH transactions with Stripe. Head to [Stripe's ACH guide](https://plaid.comhttps://stripe.com/docs/ach/index.html.md) to get started, and if you have any issues, please reach out to Stripe Support.

If you are using the [Charges and Sources API](https://plaid.comhttps://stripe.com/docs/ach-deprecated/index.html.md) , the Stripe documentation will walk you through the process.

If you are using the Payment Intents API, you will first need to create a Stripe [customer](https://plaid.comhttps://stripe.com/docs/api/customers/create/index.html.md#create_customer-payment_method) using the bank account token, then follow the [migration guide](https://plaid.comhttps://stripe.com/docs/payments/ach-debit/migrations/index.html.md#create-payment-intent) to create a Payment Intent based on the bank account, using the [manual migration flow](https://docs.stripe.com/payments/ach-direct-debit/migrating-from-another-processor#manual-bank-account-migration) . Note that you will need to contact Stripe to request access to this flow.

#### Example code in Plaid Pattern 

For a real-life example of an app that integrates a processor partner, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. (Note that while the processor token creation call in Plaid Pattern's [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) demonstrates usage of the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint for creating a processor token, Stripe integrations should use the [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) endpoint instead and create a bank account token.)

#### Troubleshooting 

##### Stripe bank account token not returned 

When a `stripe_bank_account_token` is not returned, a typical cause is that your Stripe and Plaid accounts have not yet been linked. First, be sure that your Stripe account has been [configured to accept ACH transfers](https://plaid.comhttps://stripe.com/docs/guides/ach/index.html.md) . Then, [link your Stripe account to your Plaid account](https://plaid.com/docs/auth/partnerships/stripe/index.html.md#set-up-your-plaid-and-stripe-accounts) and re-try your request.

##### Stripe::InvalidRequestError: No such token 

The `Stripe::InvalidRequestError: No such token` error is returned by Stripe when the `bank_account_token` could not be used with the Stripe API. Make sure you are not mixing Plaid's Sandbox environment with Stripe's production environment and that, if you have more than one Stripe account or more than one Plaid `client_id`, you are using the Stripe account that is linked to the Plaid `client_id` you are using.

#### Support and questions 

Find answers to many common integration questions and concerns, such as pricing, sandbox and test mode usage in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth - Wedbush | Plaid Docs

Add Wedbush to your app 
========================

#### Plaid-linked bank accounts can be connected to fund or withdraw from accounts on the Wedbush Securities platform. 

(An image of "Partnership Wedbush logo")

  

#### Overview 

Wedbush is a leading wealth management, brokerage and advisory firm, offering a complete suite of wealth management products and financial services. Plaid and Wedbush have partnered to offer a frictionless way to link investor’s bank accounts and their brokerage accounts to facilitate seamless money movement. This integration is designed with security and privacy in mind, negating the need to share sensitive account details.

#### Getting Started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Wedbush account](https://portal.wedbushfutures.com/Login) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Wedbush `processor_token`, which allows you to quickly and securely verify a bank funding source via [Wedbush's API](https://www.wedbush.com/) without having to store any sensitive banking information. Utilizing Plaid + Wedbush enables a seamless workflow for connecting external financial accounts to Wedbush.

#### Instructions 

##### Set up your accounts 

You'll need accounts at both Plaid and Wedbush in order to use the Plaid + Wedbush integration. You'll also need to enable your Plaid account for the Wedbush integration.

First, you will need to work with the Wedbush team to [sign up for a Wedbush account](https://portal.wedbushfutures.com/Login) , if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) .

To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Wedbush to enable the integration.

You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Wedbush to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Wedbush.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Wedbush `processor_token`.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has successfully
        // authenticated and selected an account to use.
        //
        // When called, you will send the public_token and the selected accounts,
        // metadata.accounts, to your backend app server.
        sendDataToBackendServer({
           public_token: public_token,
           accounts: metadata.accounts
        });
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    // Link will automatically detect the institution ID
    // associated with the public token and present the
    // credential view to your user.
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Wedbush, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account.

Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Wedbush `processor_token`. You'll send this token to Wedbush and they will use it to securely retrieve account details from Plaid.

You can create Wedbush `processor_tokens` in both API environments:

*   Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users
*   Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Wedbush Production credentials

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
} = require('plaid');


// Change sandbox to production when you're ready to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: publicToken,
  });
  const accessToken = tokenResponse.data.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'wedbush',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.data.processor_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "m8MDnv9okwxFNBV"
}
```

For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) .

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135)

#### Launching to Production 

##### Test with Sandbox credentials 

To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`.

##### Get ready for production 

Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Wedbush Production credentials prior to initiating live traffic in the Wedbush API with Plaid.

##### Support and questions 

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth - Zero Hash | Plaid Docs

Add Zero Hash to your app 
==========================

#### Use Zero Hash with Plaid Auth to embed bank account linking for ACH-funded crypto trades 

(An image of "Partnership Zero Hash logo")

  

#### Overview 

Plaid and Zero Hash have partnered to enable end users to instantly connect their bank accounts to pre-fund a wallet or facilitate buy and sell crypto trades with ACH payments. Zero Hash’s clients can use Plaid Link to instantly authenticate a user’s financial account and generate a Plaid processor token to seamlessly and securely exchange user bank account information, without having to store any sensitive data. The processor token enables Zero Hash to initiate transaction requests directly from Plaid so that customers can execute ACH payments via Zero Hash’s API.

#### Getting Started 

You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Zero Hash account](https://zerohash.com/contact/) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Zero Hash `processor_token`, which allows you to quickly and securely verify a bank funding source via [Zero Hash's API](https://docs.zerohash.com/web/) without having to store any sensitive banking information. Utilizing Plaid + Zero Hash enables a seamless workflow for connecting external financial accounts to Zero Hash.

#### Instructions 

##### Set up your accounts 

You'll need accounts at both Plaid and Zero Hash in order to use the Plaid + Zero Hash integration. You'll also need to enable your Plaid account for the Zero Hash integration.

First, you will need to work with the Zero Hash team to [sign up for a Zero Hash account](https://zerohash.com/contact/) , if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) .

To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Zero Hash to enable the integration.

You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Zero Hash to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Zero Hash.

##### Create a link\_token 

In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) .

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Integrate with Plaid Link 

Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Zero Hash `processor_token`.

```javascript
Open Link - Institution Select


  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has successfully
        // authenticated and selected an account to use.
        //
        // When called, you will send the public_token and the selected accounts,
        // metadata.accounts, to your backend app server.
        sendDataToBackendServer({
           public_token: public_token,
           accounts: metadata.accounts
        });
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();


  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    // Link will automatically detect the institution ID
    // associated with the public token and present the
    // credential view to your user.
    linkHandler.open();
  };

```

See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations.

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.

##### Write server-side handler 

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint.

The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Zero Hash, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account.

Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Zero Hash `processor_token`. You'll send this token to Zero Hash and they will use it to securely retrieve account details from Plaid.

You can create Zero Hash `processor_tokens` in both API environments:

*   Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users
*   Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Zero Hash Production credentials

```javascript
const {
  Configuration,
  PlaidApi,
  PlaidEnvironments,
  ProcessorTokenCreateRequest,
} = require('plaid');


// Change sandbox to production when you're ready to go live!
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const plaidClient = new PlaidApi(configuration);


try {
  // Exchange the public_token from Plaid Link for an access token.
  const tokenResponse = await plaidClient.itemPublicTokenExchange({
    public_token: publicToken,
  });
  const accessToken = tokenResponse.data.access_token;


  // Create a processor token for a specific account id.
  const request: ProcessorTokenCreateRequest = {
    access_token: accessToken,
    account_id: accountID,
    processor: 'zero_hash',
  };
  const processorTokenResponse = await plaidClient.processorTokenCreate(
    request,
  );
  const processorToken = processorTokenResponse.data.processor_token;
} catch (error) {
  // handle error
}
```

For a valid request, the API will return a JSON response similar to:

```json
{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "m8MDnv9okwxFNBV"
}
```

For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) .

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135)

#### Launching to Production 

##### Test with Sandbox credentials 

To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`.

##### Get ready for production 

Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Zero Hash Production credentials prior to initiating live traffic in the Zero Hash API with Plaid.

##### Support and questions 

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) .

If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

---


# Auth - Increasing pay-by-bank adoption | Plaid Docs

Increasing pay-by-bank adoption 
================================

#### Enhance discovery and conversion on bank payments via UX design 

#### Increasing Pay by bank adoption 

Properly presenting 'pay by bank' as a payment method and showcasing the convenience of using Plaid for account authentication can result in up to 2-5x more users choosing to pay by bank.

#### Payment method presentation 

Place 'Pay by bank' as the first option in a payment list, have it pre-selected with a radio button, and display [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) inline. This shows that instant verification is available and easy to use.

(An image of "Payment page with options for monthly, quarterly, or annual plans. 'Pay by bank' is selected. Bank logos displayed for selection. Total: $47.49/month.")

Example of Embedded Institution Search on Desktop

##### Embedded Institution Select default open 

Users are more likely to select 'Pay by bank' if they understand that it will be a secure, open banking-powered experience, rather than having to enter an account and routing number, which is their default expectation. Users are even more likely to use pay by bank if they see their bank's logo within Link.

Plaid will dynamically show the user the most popular institutions for your application in their area, or you can customize this list via the Plaid Dashboard.

###### Recommendations: 

*   Show as many logos as possible, following the [breakpoint guidance](https://plaid.com/docs/link/embedded-institution-search/index.html.md#customization-options) , in order to increase the likelihood that the user will see their bank.
*   By providing the user’s phone number, you can activate the streamlined version of [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md#pre-filling-phone-numbers-for-faster-account-verification) , which has been shown to drive a 2x increase in bank payments adoption for returning users.
*   Ensure Embedded Institution Search is visible by default, without requiring the user to first select 'Pay by bank'.

#### Using accordion open 

If the Embedded Institution Search inline display option is not available to you due to design or technical constraints, use an "accordion open" technique. Once the user selects 'Pay by bank', render the Embedded Institution Search for easy user comprehension of their next steps to add a bank account.

(An image of "Payment page with options for monthly, quarterly, annual plans. Select pay by bank or card. Pet insurance $47.49/month. Pay button.")

Example of Embedded Institution Search on Desktop

###### Recommendations: 

*   Labeling the payment method as 'Pay by bank' and adding an appropriate CTA such as 'instantly verify your bank account' will help users understand that your pay by bank flow is powered by open banking.
*   Use "accordion open" if necessary to display Embedded Institution Search.

#### Configure Account Select 

The [Account Select](https://plaid.com/docs/link/customization/index.html.md#account-select) option "Enabled for one account" setting configures the Link UI so that the end user may only select a single account. This is the appropriate configuration for most pay-by-bank use cases. You can configure this option in the Dashboard, under [Link > Link Customization > Account Select](https://dashboard.plaid.com/link/account-select) .

#### Enable Database Auth 

Although most users prefer signing into their bank account via open banking, some prefer to provide their account and routing numbers manually.

##### Recommendations: 

*   To support both populations, enable [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) .

Database Auth is appropriate for low-to-medium-risk scenarios, such as recurring bill payments and loan repayments. If you experience high rates of fraud or ACH returns in your payments flow, you should not enable Database Auth.

#### Auth Type Select 

For user populations with a higher propensity to link accounts manually, Plaid provides [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) as an upfront option to the end user to choose between open banking login or manual account connection. Otherwise, this option will only be displayed if the user can't find their bank or encounters an error trying to connect.

Examples of populations that may prefer manually linking include business users (who may not have access to their organization's online banking credentials) or users who are less comfortable with technology.

(An image of "Pay by bank: Select payment method with bank search and Auth Type Select. Monthly plan, $47.49/mo summary visible.")

Embedded Institution Search with Auth Type Select enabled

Auth Type Select will increase the percentage of users whose proposed payments cannot be evaluated for risk. Use [Signal](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) and [Identity Match](https://plaid.com/docs/identity/index.html.md#using-identity-match-with-micro-deposit-or-database-items) with manually verified Items to reduce the risk of return. If you experience high rates of fraud or ACH returns in your payments flow, you should not enable Auth Type Select.

##### Recommendations: 

*   Enable Auth Type Select if you have reason to believe that your user population prefers to link accounts manually and your risk profile can tolerate lower coverage of anti-fraud and anti-ACH-return checks.

---


# Balance - Add Balance to your app | Plaid Docs

Add Balance to your app 
========================

#### Use Balance to fetch real-time balance data 

In this guide, we'll start from scratch and walk through how to use [Balance](https://plaid.com/docs/api/products/balance/index.html.md) to retrieve real-time balance information. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to note that you should _not_ include `balance` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) products array; you can then skip ahead to [Fetching balance data](https://plaid.com/docs/balance/add-to-app/index.html.md#fetching-balance-data) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.

`balance` cannot be used as a product when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . You must create the `link_token` with the product or products you will be using with Balance, instead. You will then automatically get access to the Balance product.

##### Create a link\_token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Fetching Balance data 

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved balance data for an account, you can then use it to evaluate whether a potential transaction will go through. For more detailed information on the schema returned, see [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { AccountsGetRequest } = require('plaid');


// Pull real-time balance information for each account associated
// with the Item
const request: AccountsGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.accountsBalanceGet(request);
  const accounts = response.data.accounts;
} catch (error) {
  // handle error
}
```

Example response data is below.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "balances": {
        "available": null,
        "current": 410,
        "iso_currency_code": "USD",
        "limit": 2000,
        "unofficial_currency_code": null
      },
      "mask": "3333",
      "name": "Plaid Credit Card",
      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
      "subtype": "credit card",
      "type": "credit"
    },
    {
      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "credit_details",
      "identity",
      "investments"
    ],
    "billed_products": ["assets", "auth", "liabilities", "transactions"],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "qk5Bxes3gDfv4F2"
}
```

#### Tutorial and example code in Plaid Pattern 

For a real-life example of an app that incorporates Balance, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Balance data to check for sufficient funds before a funds transfer. The Balance code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L211-L234) .

For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Balance - Introduction to Balance | Plaid Docs

Introduction to Balance  
=========================

#### Retrieve real-time balance information to prevent NSFs and ACH returns 

Get started with Balance

[API Reference](https://plaid.com/docs/api/products/balance/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/6786ccc5a048a5f1cf748cb5?zoom=100)

#### Overview 

Balance is Plaid's product for receiving real-time Balance information via [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) . This real-time Balance data can be used to see if an account has sufficient funds before using it as a funding source for a money transfer, helping you to avoid ACH returns. Balance is available for use exclusively in combination with other Plaid products, such as [Auth](https://plaid.com/docs/auth/index.html.md) for money movement or account funding use cases or [Transactions](https://plaid.com/docs/transactions/index.html.md) for personal finance use cases.

[Prefer to learn by watching? Get an overview of how Balance works in just 3 minutes!](https://www.youtube.com/watch?v=t7OAIoD8K4g)

#### Balance data 

```json
"balances": {
  "available": 100,
  "current": 110,
  "iso_currency_code": "USD",
  "limit": null,
  "unofficial_currency_code": null
}
```

#### Cached and realtime balance 

You can retrieve cached balance data for any Item (except for Items with manual connections, such as those using Same-Day Microdeposits) by calling the free-to-use [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint. Many Plaid products other than Balance also provide cached balance data as part of the `accounts` object. Because this data is cached, it is not suitable for situations where you need real-time balance information. The frequency with which cached balance data is updated varies depending on the product. An Item with Transactions, for example, may update cached balances once a day or more, while an Item with only Auth may update every 30 days or even less frequently.

For retrieving real-time balance for payments use cases, only [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) should be used. The exception is immediately after an Item has been linked, when the balance information is guaranteed to be recent. Note that because Balance always retrieves fresh data from the institution, latency will be higher when calling [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) than when calling other Plaid endpoints. While [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) usually takes under 5 seconds, the latency will vary by institution, and in some cases it may take 30 seconds or more to retrieve balance information.

If you want to evaluate the risk of an ACH return and need lower latency than [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) , try [Signal](https://plaid.com/docs/signal/index.html.md) . Signal uses machine learning instead of real-time balance checks to evaluate the risk of an ACH return, and can return results in approximately one second or less. For details, see [Balance vs. Signal comparison chart](https://plaid.com/docs/payments/index.html.md#balance-and-signal-comparison) .

#### Current and available balance 

Balance typically returns both current and available balance information. For fraud detection and insufficient funds (NSF) prevention use cases, available balance should be used, as it represents predicted balance net of any pending transactions, while current balance does not take pending transactions into account.

Available balance indicates balance that is available to spend, which is not the same as the overall value of the account. For example, for credit accounts, it indicates the amount that can be spent without hitting the credit limit (net of any pending transactions), while in investment accounts, it indicates the total available cash.

In some cases, a financial institution may not return available balance information. If that happens, you can calculate available balance by starting with the current balance, then using the [Transactions](https://plaid.com/docs/transactions/index.html.md) product to detect any pending transactions and adjusting the balance accordingly.

##### Typical balance fill rates by field 

| Field | Typical fill rate |
| --- | --- |
| Current balance | 99% |
| Available balance | 91% |

#### Sample app code 

For a real-life example of an app that incorporates Balance, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Balance data to check for sufficient funds before a funds transfer. The Balance code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L211-L234) .

For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

#### Balance pricing 

Balance is billed on a [flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) , meaning you will be billed once for each successful call to [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

To get started building with Balance, see [Add Balance to your App](https://plaid.com/docs/balance/add-to-app/index.html.md) .

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Balance - Troubleshooting | Plaid Docs

Troubleshooting Balance 
========================

#### API error responses 

If the problem you're encountering involves an API error message, see [Errors](https://plaid.com/docs/errors/index.html.md) for troubleshooting suggestions.

#### Inaccurate balance 

##### Common causes 

*   The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint is being used instead of [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) for real-time data.
*   Available balance is being reported when the user expects to see current balance, or vice-versa.

##### Troubleshooting steps

---


# Beacon - Introduction to Beacon | Plaid Docs

Introduction to Beacon (beta)  
===============================

#### Learn how to fight fraud with the Plaid Beacon network 

#### API Reference 

View Beacon requests, responses, and example code

[View Beacon API](https://plaid.com/docs/api/products/beacon/index.html.md)

#### Overview 

Beacon (US only) helps prevent fraud by detecting data associated with stolen or synthetic identities, account takeover fraud, or breaches. You can create blocklists based on data reported by the Beacon network, or based on first-party fraud attempts on your own app. Beacon is available free of charge.

An optional paid feature, Beacon Account Insights, is available to customers who want to build their own risk analysis on top of Plaid's Beacon data. Beacon Account Insights includes risk-related details such as account age, recent PII changes on the account, and recent failed login attempts. For a full list of data reported by Bank Account Insights, see the [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) response schema.

Beacon is currently in beta and available to select customers on a limited basis. To request access, [contact Sales](https://plaid.com/products/beacon/#contactForm) or your Account Manager.

#### Integration setup 

Select group for content switcher

Without Identity VerificationWith Identity Verification

##### Initial setup 

1.  [Create a Beacon program](https://dashboard.plaid.com/sandbox/beacon/programs/new) via the Dashboard.
    *   For best results, disable "auto flag reported user" under the "data breach hits" section, unless you have a specific business reason to enable it. Because so many users have been exposed to data breaches, enabling auto-flagging for data breach hits will result in a large number of users entering the review queue. All other automatically-selected options should be left enabled for most use cases.
2.  Take note of the beacon program ID, which is the portion of the URL after the `/` when viewing the program in the Dashboard, e.g. `becprg_7Fn5XcPhXnJJyU`. You will need this id when calling [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) and other endpoints.
3.  (Optional) For best results, backfill six months of existing data into Beacon. This should include both known-good and known-fraudulent users. To backfill, call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) for each user, making sure to include any known instances of fraud in the `report` object.

Make sure to always use the same `client_user_id` when referring to the same end user, whenever you call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) , or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

##### User creation 

1.  To create a new user, call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) .
2.  (Optional) To be alerted for the accidental creation of potential duplicate users, listen for the [DUPLICATE\_DETECTED](https://plaid.com/docs/api/products/beacon/index.html.md#duplicate_detected) webhook. You can investigate potential duplicates via the Dashboard (when configuring your Beacon template, you can set all detected duplicates to enter the review queue by default) or by calling [/beacon/duplicate/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconduplicateget) .

##### Reviewing and reporting fraud signals 

1.  Review any Beacon hits via the Dashboard, to clear or reject the user.
2.  If you become aware of any fraud committed by a user, report it to the network by clicking the "Report Fraud" button in the Beacon Dashboard or by calling [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) . To learn more about how to properly categorize fraud, see the [Fraud Reporting Guide](https://view-su2.highspot.com/viewer/3ba173969f637a61e6e9d8e41eba083b) .
3.  (Optional) To monitor for fraud on an ongoing basis, listen for the [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) webhook to be alerted to new fraud reports for any Beacon user in your system. When this webhook fires, to get more details on the report, use the Dashboard, or call [/beacon/report\_syndication/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationget) .
4.  (Optional) If you are monitoring for fraud on an ongoing basis, call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) when you are aware of any changes to user data (such as name, address or phone number) or if the user links a new account. Calling [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) will immediately re-run fraud checks for the user and may generate Beacon hits.

##### Using Beacon Account Insights (optional) 

Beacon Account Insights is an optional paid feature that allows you to build your own risk analysis on top of Plaid-reported risk signals. Reported risk signals include account age, recent PII changes on the account, and recent failed login attempts. For a full list of returned fields, see the API Reference for [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) .

1.  Create a Link token and use it to launch Link, following the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , be sure to include `beacon` in the `products` array.
2.  The end user will then complete a Link session, resulting in a `public_token`, which can be obtained by either the `onSuccess` client-side callback or by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) .
3.  Use [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token`.
4.  Call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) to associate the `access_token` with the Beacon user.
5.  Call [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) to get account insights.

Before following these steps, set up [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) following the [Identity Verification integration process](https://plaid.com/docs/identity-verification/index.html.md#identity-verification-integration-process) .

##### Initial setup 

1.  [Create a Beacon program](https://dashboard.plaid.com/sandbox/beacon/programs/new) via the Dashboard.
    *   For best results, disable "auto flag reported user" under the "data breach hits" section, unless you have a specific business reason to enable it. Because so many users have been exposed to data breaches, enabling auto-flagging for data breach hits will result in a large number of users entering the review queue. All other automatically-selected options should be left enabled for most use cases.
2.  Open the Identity Verification template editor and select your Beacon program under Setup > Beacon Fraud Screening, then click "publish".
3.  (Optional) For best results, backfill six months of existing data into Beacon.
    *   If you are adding Beacon to an Identity Verification deployment that has already been running in Production, then to backfill, call [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) to report each known incident of fraud, using the `beacon_user_id` obtained from calling [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , and making sure to include any known instances of fraud in the `report` object.
    *   To backfill users that have _not_ been through an Identity Verification session, call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) for each user, making sure to include any known instances of fraud in the `report` object.

Make sure to always use the same `client_user_id` when referring to the same end user, whenever you call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) , or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

##### User creation 

1.  To add a new user, launch Link as normal and have the user go through an Identity Verification session. You should _not_ update the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `products` array to include `beacon`.
2.  To get the `beacon_id` for the user, call [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) . There is no need to call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) .

##### Reviewing and reporting fraud signals 

1.  Review any Beacon hits via the Dashboard, to clear or reject the user.
2.  If you become aware of any fraud committed by a user, report it to the network by clicking the "Report Fraud" button in the Beacon Dashboard or by calling [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) . To learn more about how to properly categorize fraud, see the [Fraud Reporting Guide](https://view-su2.highspot.com/viewer/3ba173969f637a61e6e9d8e41eba083b) .
3.  (Optional) To monitor for fraud on an ongoing basis, listen for the [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) webhook to be alerted to any new fraud reports.
4.  (Optional) If you are monitoring for fraud on an ongoing basis, call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) when you are aware of any changes to user data (such as name, address or phone number) or if the user links a new account. Calling [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) will immediately re-run fraud checks for the user and may generate Beacon hits.

In the Link flow, a user will see a "successfully verified" screen if there were no Beacon (or Monitor, if using) hits and all required Identity Verification checks passed. If there were any hits, or if Identity Verification checks failed, the user will see the "verification failed" screen and be placed in the pending review state, where you can review their session from the Dashboard.

##### Using Beacon Account Insights (optional) 

Beacon Account Insights is an optional paid feature that allows you to build your own risk analysis on top of Plaid-reported risk signals. Reported risk signals include account age, recent PII changes on the account, and recent failed login attempts. For a full list of returned fields, see the API Reference for [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) .

1.  Create a Link token and use it to launch Link, following the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , be sure to include `beacon` in the `products` array.
2.  The end user will then complete a Link session, resulting in a `public_token`, which can be obtained by either the `onSuccess` client-side callback or by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) .
3.  Use [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token`.
4.  Call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) to associate the `access_token` with the Beacon user.
5.  Call [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) to get account insights.

#### Adding Beacon Account Insights to existing Items 

1.  Send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Beacon does not yet support `additional_consented_products`; you will set `"products": ["beacon"]` when initializing update mode.
2.  Call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) (or, if the user was already created, [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) ), providing the Item's `access_token`(s), to associate the Beacon user with the Item.
3.  Call [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) to get account insights.

#### Beacon workflows 

All Beacon hits generate a `pending_review` status and must be reviewed in the Dashboard to resolve into a `cleared` or `rejected` state, unless the hit is for a first-party fraud report generated by your organization. Those hits will move the user directly to a `rejected` status.

When creating your Beacon template, you can optionally configure whether a detected duplicate should be moved into `pending_review` state.

#### Testing Beacon in Sandbox 

In Sandbox, use the [Leslie Knope test user](https://plaid.com/docs/identity-verification/testing/index.html.md#primary-test-user-leslie-knope) to generate Beacon hits and test the Pending Review state.

To generate a Cleared status, you can use any user data that you have not already screened.

To generate a Rejected status, run a Beacon screening, report a `first_party` fraud incident associated with the user, then run another screening on the user.

When testing in Sandbox, re-using the same test user repeatedly will degrade performance over time. If running automated test suites, use randomly generated user data, rather than re-using the same data, in order to avoid performance issues. Similarly, it is not recommended to create large number of duplicate users to test duplicate user detection.

#### Beacon pricing 

Participation in the Plaid Beacon Network is free of charge. The optional Beacon Account Insights feature, using the [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) endpoint, is billed under [a per-request flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) .

---


# Changelog | Plaid Docs

Plaid changelog 
================

#### Track changes to the Plaid API and products 

#### Overview 

This changelog tracks updates to the Plaid API and changes to the Plaid mobile SDKs, Link flow, functionality, and APIs. The changelog is updated at least once per month. Updates that affect only products or features in beta or limited release may not always be reflected. Improvements to the Dashboard, institution connectivity, or data availability may not always be reflected.

Link SDKs are released on GitHub. A summary of updates will be posted here. For a more complete and detailed record of Link SDK changes, see the GitHub changelogs: [iOS](https://github.com/plaid/plaid-link-ios/releases) , [Android](https://github.com/plaid/plaid-link-android/releases) , [React Native](https://github.com/plaid/react-native-plaid-link-sdk/releases) , [React](https://github.com/plaid/react-plaid-link) .

Plaid's officially supported libraries are updated frequently. For details, see the GitHub changelogs: [Python](https://github.com/plaid/plaid-python/blob/master/CHANGELOG.md) , [Node](https://github.com/plaid/plaid-node/blob/master/CHANGELOG.md) , [Ruby](https://github.com/plaid/plaid-ruby/blob/master/CHANGELOG.md) , [Java](https://github.com/plaid/plaid-java/blob/master/CHANGELOG.md) , [Go](https://github.com/plaid/plaid-go/blob/master/CHANGELOG.md) .

#### Subscribe to updates 

[Subscribe to this changelog via RSS](https://cdn.feedcontrol.net/8259/13425-kjU6T4Te5FUvO.xml) .

##### August 27, 2025 

For the Dashboard:

*   The "Team Management" permission is no longer required to access the Link Analytics page. Any verified user can now access this page. The "Link Customization Write Access" permission is now required to access Link Customization / Template editor pages instead of the "Team Management" permission.

For Link:

*   Released [Plaid Android SDK 5.3.2](https://github.com/plaid/plaid-link-android/) , including an upgrade to version 3.25.5 of the `com.google.protobuf:protobuf-kotlin-lite` library.

For Auth:

*   Improved the Link UI on the "Are you sure?" screen displayed when an end user attempts to close Link without connecting an account. The new screen more prominently displays the option to link an account via non-credential based flows (if enabled), resulting in increased Link conversion.

For Plaid Check Consumer Report:

*   Added support for Consumer Report in the [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) Link UI. This Link configuration is recommended when using Consumer Report alongside Auth as part of a single Link flow that supports bank account linking for both underwriting and repayment.

For Layer:

*   Added [Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) , which expands the number of users who can have their personal information prefilled with Layer, even if their phone number is not Layer eligible. To learn more and add Extended Autofill to your existing integration, see [Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) .

For Transfer:

*   Added monthly Transfer reconciliation report emails. This feature is currently opt-in; to request access, contact your Plaid Account Manager.

##### August 17, 2025 

For the Plaid Dashboard:

*   Added audit logs of Dashboard actions. Audit logs are available to admins via the Dashboard under Settings -> Audit Logs. Currently, core Dashboard actions are logged; logging for actions in product-specific Dashboards is not yet available. Audit logs are available only to customers on Premium Platform Support packages. To learn more about upgrading to a Premium Platform Support package, contact your Account Manager.

For all products:

*   For [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) , added optional `reason_code` and `reason_note` fields. Using these fields when removing an Item can help Plaid identify fraud and bad actors in the Plaid Network, improving anti-fraud data for all Plaid customers.

For Plaid Link:

*   Released [Plaid Android SDK 5.3.1](https://github.com/plaid/plaid-link-android/) , fixing a bug in which screens did not properly resize for the keyboard on Android 15+.

For Plaid Check Consumer Report:

*   Added the ability to generate Verification of Assets (VoA) and Employment Refresh reports suitable for providing to GSEs. To generate these reports, use the `base_report.gse_options` field when calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   Added the ability to create and manage OAuth tokens to securely share consumer report data with Plaid partners Experian, Fannie Mae, and Freddie Mac. For more details, see [Consumer Report OAuth data sharing](https://plaid.com/docs/check/oauth-sharing/index.html.md) .

For Identity Verification:

*   In the Document Verification `analysis` object, added the `aamva_verification` object to report results from the American Association of Motor Vehicles Administrators (AAMVA) Drivers License Data Verification service. This object is currently in beta. To receive AAMVA data, you must enable the corresponding feature in your Identity Verification template under the "DMV/Secretary of State Validation" header in the Workflow tab of the Template Editor. This object will only be populated for US drivers licenses in [participating states](https://www.aamva.org/it-systems-participation-map?id=594) .

For Investments:

*   Removed the `sedol` field from responses, as this field was only available for stocks that trade on London Stock Exchange and to customers that had the appropriate licenses. The `sedol` field will now be `null` for all securities.
*   Added `subtype` identifiers to the `security` object to specify the type of a security in more detail. New subtype values are: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`.

For Transfer:

*   In the [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) response `rfp` object, added `max_amount` and `iso_currency_code` fields.
*   Added [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) endpoint.

##### August 6, 2025 

For Plaid Link:

*   Released a visual refresh of the Link UI to match the Plaid brand refresh. This update does not change the functionality of Link.
*   Released [Plaid iOS SDK 6.4.0](https://github.com/plaid/plaid-link-ios) , adding `issueDescription` and `issueDetectedAt` to `EventMetadata`.
*   Released [Plaid Android SDK 5.3.0](https://github.com/plaid/plaid-link-ios) , adding `issueDescription` and `issueDetectedAt` to `EventMetadata`, the event `LAYER_AUTOFILL_NOT_AVAILABLE`, and supporting the `dateOfBirth` parameter for Layer.
*   Released [Plaid React Native SDK 12.4.0](https://github.com/plaid/react-native-plaid-link-sdk) . This release updates the Android SDK to 5.3.0 and the iOS SDK to 6.4.0. It also includes updates to the example application to make it more clear how to use Layer and Sync Financekit.
*   Released [Plaid React Link SDK 4.1.1](https://github.com/plaid/react-plaid-link) , patching a build issue introduced in version 4.1.0.

For Plaid Check Consumer Report:

*   Improved income forecasting calculations in the Income Insights report:
    *   Tax refunds and inactive income streams will no longer contribute to forecasted income.
    *   Income forecasts will now use all available income history (up to 5 years) rather than a 90 day maximum.
*   During the week of August 18, 2025, Data Transparency Messaging (DTM) will be disabled for Consumer Report until further notice. No action is needed on the part of impacted customers. For Link sessions that include both Plaid Check products and Plaid Inc. products in a single Link flow, DTM will still be used for Plaid Inc. products if it is otherwise enabled for the Link flow.

For Signal:

*   Beginning September 1, 2025, when [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) or [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) is called with an unknown `client_transaction_id` (one that was never submitted to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) ), these endpoints will return an error instead of a success response. This change better reflects that these endpoints should only be used to report returns or decisions on previously-evaluated transactions.

For Transfer:

*   Added more granular Transfer-specific permissions controls to the Dashboard. For more details, see [Transfer Dashboard permissions](https://plaid.com/docs/transfer/dashboard/index.html.md#dashboard-permissions) . To manage your team's Transfer permissions, use the [Dashboard -> Team Settings -> Members page](https://dashboard.plaid.com/settings/team/members) .

##### August 4, 2025 

For Plaid Link:

*   Released [Plaid React Link SDK 4.1](https://github.com/plaid/react-plaid-link) , with support for passing date of birth for Layer autofill.

##### July 30, 2025 

For Plaid Link:

*   Released [Plaid iOS SDK 6.3.2](https://github.com/plaid/plaid-link-ios) , with fixes to XCFramework signing issue.
*   Released [Plaid iOS SDK 6.3.1](https://github.com/plaid/plaid-link-ios) , with updated Layer Submit API, new Layer event `LAYER_AUTOFILL_NOT_AVAILABLE`, and exposing Finance Kit sync simulated behavior to Objective-C (React Native).
*   Released [Plaid React Native SDK 12.3.2](https://github.com/plaid/react-native-plaid-link-sdk) , updating the React Native SDK to use Plaid iOS SDK 6.3.2.
*   Released [Plaid React Native SDK 12.3.1](https://github.com/plaid/react-native-plaid-link-sdk) , updating the React Native SDK to use Plaid iOS SDK 6.3.1.

##### July 25, 2025 

For Plaid Link:

*   Released [Plaid Android SDK 5.2](https://github.com/plaid/plaid-link-android/) , with new event names and a new event metadata field, improved behavior for `destroy()`, a smaller SDK size, and removal of unused dependencies. For more details, see the [release notes](https://github.com/plaid/plaid-link-android/releases/tag/v5.2.0)
*   Released [Plaid React Native SDK 12.3.0](https://github.com/plaid/react-native-plaid-link-sdk) , updating the React Native SDK to use Plaid Android SDK 5.2 and Plaid iOS SDK 6.3.
*   Began rolling out a progress bar in the Link UI to all customers. During testing, Link sessions with the progress bar displayed showed a statistically significant increase in Link conversion.

##### July 24, 2025 

For the Plaid Dashboard:

*   Improved the user experience for OAuth registration and onboarding:
    *   OAuth registration status is now displayed more prominently within the Dashboard
    *   Added estimated timelines for institution enablement
    *   Accelerated the OAuth registration process, resulting in shorter waits for OAuth enablement
    *   Added more complete list of institutions that use OAuth and their enablement statuses
    *   Added detailed and actionable error messages if an error occurred during registration
    *   Customers on Growth or Custom plans will automatically be enabled for access to Charles Schwab; customers on Pay-as-you-go plans will still need to explicitly request Schwab access
*   Added the ability to export the list of team members to CSV.
*   Added the ability for customers with Premium Platform Support Packages to self-serve enable SCIM in the Dashboard without contacting Plaid Support or their Account Manager.
*   Removed Data Quality related Known Issues the Dashboard, as these issues were often described in vague terms, causing customers to think they were encountering a known issue when they were not. Removing these from the Known Issues section of the Dashboard helps Plaid more accurately identify data quality issues and reduces customer confusion caused by following the wrong Known Issue. Connectivity-related Known Issues are still reported in the Dashboard.
*   When users attempt a Dashboard action they don't have permissions for, they will now be shown a list of admins whom they can contact to request permission.

For Plaid Link:

*   Released [React Native Plaid Link SDK 12.2.1](https://github.com/plaid/react-native-plaid-link-sdk) , with bug fix for the error message "PLKEnvironmentDevelopment not defined".
*   Released [Plaid iOS SDK 6.3](https://github.com/plaid/plaid-link-ios/) , with new event names and a new event metadata field, enhancements for the SwiftUI API, and improved FinanceKit testing capabilities. For more details, see the [release notes](https://github.com/plaid/plaid-link-ios/releases/tag/6.3.0) .

For Plaid Check Consumer Reports:

*   Added support for Verification of Assets and Employment Refresh for mortgage lenders via [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) . This feature is in Early Availability; contact Sales or your Account Manager to learn more.
*   Improved the accuracy of insufficient funds (NSF) transaction calculations, leading to fewer transactions being reported under the `nsf_overdraft_transactions_count` fields.
*   For Income Insights, improved the accuracy of income categorization, forecasted income, and historical income.
*   Added institution details (`institution_name` and `institution_id`) to [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) response.
*   Added `require_identity` boolean to options object in [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests. If set to `true` and user identity data is not available, CRA report creation will fail, and you will not be charged.
*   Updated and made consistent maximum values `days_required` and `days_requested` when generating a CRA report across multiple endpoints. The maximum value for `days_requested` is now 731 and the maximum value for `days_required` is 184.
*   For Partner Insights, added `client_report_id` to partner insights response.

For Investments:

*   Improvements and bug fixes to holdings valuations, such as better reflecting the value of unvested shares.

For Payment Initiation:

*   Added `error` field to responses of [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) containing error details when the payment fails.
*   Added support for cursors to [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) .
*   Added error field to `WALLET_TRANSACTION_STATUS_UPDATE` webhook and to responses of [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) .

For Transactions:

*   Added [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) endpoint, which can be used to add custom transactions to the `user_transactions_dynamic` Sandbox test user.
*   Added the `user_ewa_user`, `user_yuppie`, and `user_small_business` Sandbox test users for persona-based testing of realistic Transactions data.
*   Added `account_numbers` field to `counterparty` object.

For Transfer:

*   Added `wire_return_fee` to transfer and transfer event objects.

##### June 12, 2025 

*   Released [Plaid Protect](https://plaid.com/docs/protect/index.html.md) , Plaid's new anti-fraud solution.
*   Released [Premium Link Analytics](https://plaid.com/docs/link/measuring-conversion/index.html.md#premium-link-analytics) , a new Dashboard feature with advanced analytics insights on Link usage and conversion. Premium Link Analytics is available at no extra charge to all customers with Premium Support Packages. To learn more about upgrading to a Premium Support Package, contact your Account Manager.
*   Launched Plaid's AI Toolkit, including the Dashboard MCP Server, Sandbox MCP Server, LLM-friendly documentation, and vibe coding guides. For more details, see the [Resources page](https://plaid.com/docs/resources/index.html.md#ai-developer-toolkit) .
*   Released version 5.1.1 of the [Plaid Android Link SDK](https://github.com/plaid/plaid-link-android) and version 6.2.1 of the [iOS Link SDK](https://github.com/plaid/plaid-link-ios) . These updates both contain the ability to detect usage of [Plaid Link for Flutter](https://github.com/jorgefspereira/plaid_flutter) , allowing Plaid to better troubleshoot integration issues by distinguishing between Flutter and non-Flutter usage.

##### June 9, 2025 

For Link:

*   Released version 5.1.0 of the [Plaid Android Link SDK](https://github.com/plaid/plaid-link-android) . Improvements include a bug fix for edge-to-edge layout overlap issue on Android 15+, 20% smaller SDK size, and removal of the `org.bouncycastle:bcpkix-jdk15to18` dependency.
*   Began rolling out a new pane added to the end of the Link flows for Assets and Bank Income, prompting end users to enroll in Plaid Passport for faster credit application flows in the future. This pane occurs after the end user has successfully completed Link and therefore has no impact on Link conversion. This pane will be released to all eligible customers by the end of August.

For Plaid Check Consumer Reports:

*   Introduced a rate limit of 100 requests per minute for all Plaid Check endpoints.

For Transfer:

*   Plaid Transfer now supports Instant Payments (pay-ins) via request-for-payment (RfP) on the RTP network.

##### June 3, 2025 

*   Announced the availability of the [Plaid Dashboard MCP server](https://plaid.com/docs/resources/mcp/index.html.md) . This service allows you to access Dashboard-based services such as Link analytics data, API usage, and the Item debugger via an LLM agent. More tools and the ability to use additional platforms will be added soon.
*   Released Plaid Link [iOS SDK 6.2.0](https://github.com/plaid/plaid-link-ios/releases/tag/6.2.0) . This version features a 33% smaller package size, a `showGradientBackground` option for customizing Link appearance, and a new `onLoad` callback from `Plaid.create` to help detect when Plaid is ready to present.

For Auth:

*   Released [Account Verification Analytics](https://dashboard.plaid.com/account-verification/analytics) , Dashboard-based reports of Auth and Identity Match activity showing usage levels and conversion metrics by Auth method.

For Plaid Check Consumer Reports:

*   For [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , deprecated `report.items.accounts.account_insights` in favor of the [attributes field](https://plaid.com/docs/api/products/check/index.html.md#cra-check_report-base_report-get-response-report-attributes) , which aggregates insights across accounts.
*   Announced the availability of a new model version (v4) for their scores that are provided in Partner Insights. Starting on June 2, 2025, customers using Partner Insights can choose to use the latest version when calculating the scores by specifying it in the `prism_versions` object when calling [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) . If no version is specified, Plaid will default to the current version (v3) available now. Starting in November 2025, customers will be required to specify a `prism_version` when calling Partner Insights endpoints.

For Transfer:

*   Added [automatic Sandbox simulations](https://plaid.com/docs/transfer/sandbox/index.html.md#automatic-sandbox-simulations) , allowing you to create test transactions in Sandbox that will automatically move through the transfer lifecycle, without requiring you to manually progress them to the next state.

##### May 20, 2025 

For Enrich:

*   Removed the legacy `category_id` and `category` fields for all customers enabled for the Transactions product on or after May 5, 2025. Customers should use the `personal_finance_category` field instead.

For Transactions:

*   Removed the legacy `category_id` and `category` fields for all customers enabled for the Transactions product on or after May 5, 2025. Customers should use the `personal_finance_category` field instead.

##### May 14, 2025 

For Auth:

*   Announced PNC's new TAN expiration policy. All PNC Items with TANs will require the user to have authorized or re-authorized consent within the past 12 months. If the user has not done so, the TAN will stop working and the Item will enter an `ITEM_LOGIN_REQUIRED` state. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) .

For Layer:

*   Added `android_package_name` to [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) .

For Plaid Check Consumer Reports:

*   Updated `average_inflow_amount` field to be positive.

For Transfer:

*   Announced PNC's new TAN expiration policy. All PNC Items with TANs will require the user to have authorized or re-authorized consent within the past 12 months. If the user has not done so, the TAN will stop working and the Item will enter an `ITEM_LOGIN_REQUIRED` state. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) .

##### May 5, 2025 

*   Announced new `INSTITUTION_RATE_LIMIT` error and behavior for when an institution is experiencing excessive API traffic to realtime endpoints. This error will be rolled out to all customers by the end of May 2025.

For Transfer:

*   Added `expected_funds_available_date` to the Transfer object.

##### April 24, 2025 

*   Released a new [migrations page](https://dashboard.plaid.com/activity/status/migrations) on the Dashboard, showing all institutions with planned or ongoing migrations to OAuth. Drilling in to each institution, you can now view the migration timeline and impact to existing Items.
*   Added support for Austria and Finland. For details of supported institutions and products, see [European bank coverage](https://plaid.com/docs/resources/index.html.md#european-bank-coverage-explorer) .
*   Added `USER_PERMISSION_REVOKED` webhook support for American Express.

For Layer:

*   Added the ability to configure Layer sessions in the Dashboard.
*   In [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) , moved the `user_id` field into the `user` object.
*   Released React Native SDK 12.1.1, with a new `destroy()` method to support Layer.

For Link:

*   Released React Native SDK 12.1.1, with a new `destroy()` method to support Plaid Layer.
*   Released React SDK 4.0.1, with support for React 19.
*   Webview-based integration modes are no longer allowed for new customers. All new customers using mobile webview-based apps should use the Hosted Link integration mode if they can't use Plaid's SDKs. Existing customers using webview integration modes are not currently impacted.
*   Announced a combined phone number and consent pane for the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) , to be rolled out to all customers in May. This change increases conversion by reducing the number of screens the end user has to complete. It does not require any integration work on your part to adopt. Both the `CONSENT` and `SUBMIT_PHONE` `TRANSITION_VIEW` Link analytics events will fire when this screen is reached.

For Plaid Check Consumer Reports:

*   Expanded support for Silent Network Authentication (SNA), a secure, lower friction way to verify a user’s phone number using their mobile network carrier. Once eligible users submit their phone number, they will see a loading pane in Link in lieu of the OTP pane. If SNA cannot verify a user’s phone number, then it will fall back to OTP for verification. SNA is available for Plaid Check Consumer Reports on both iOS and Android and is compatible with T-Mobile, Verizon, and AT&T. SNA will be rolled out to all eligible Consumer Report sessions by the end of May. No work is required on your part to support SNA. SNA is supported on Android SDK versions >=5.6.0 and iOS SDK versions >=4.7.9. To get the latest performance improvements for SNA, it is strongly recommended that all Plaid Check customers using Plaid's mobile SDKs upgrade to iOS SDK >=6.0.1 (or React Native iOS >=12.0.2).
*   Date of birth is now required within the consumer report user identity object for [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) .
*   Added `warnings` to responses for [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) and [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) . `warnings` is populated when Plaid successfully generated a report, but encountered an error when extracting data from one or more Items.
*   A user's phone number can now be pre-filled in Link using data from the `consumer_report_user_identity` object if the phone number is not pre-filled via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   A new toggle on the last pane of the Link flow enables users to opt-in to a faster way to share their consumer reports in the future.
*   Updated the list of [Cash flow updates webhooks (beta)](https://plaid.com/docs/api/products/check/index.html.md) .

For Signal:

*   Added `triggered_rule_details` to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response.

For Transactions:

*   Updated the response schema for [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) endpoint to allow `null` account objects. This change only impacts Transactions processor partners.

##### March 31, 2025 

For Identity Verification:

*   Announced the rollout of Age Estimation and Biometric Deduplication features. On May 1, 2025, Plaid will backfill historical ID document and liveness data and enable these features for all customers using IDV templates with ID document and/or liveness enabled, free of charge. Any Plaid customer who wants to opt out of this functionality should contact their Account Manager.

##### March 25, 2025 

*   Added a "copy link" button to the Team switcher page in the Dashboard, allowing Dashboard users to access a persistent link to their team.

For Assets:

*   To minimize data access, Assets no longer requests the Investments data scope by default. To use the Investments add-on, `investments` must now be specified in the `optional_products` array when initializing Link.

For Layer:

*   Added the [LAYER\_AUTHENTICATION\_PASSED webhook](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) .

For Investments:

*   Added Vanguard access via OAuth. Access to Vanguard is no longer restricted during peak market hours.

For Plaid Check Consumer Reports:

*   Broke up the existing `DATA_UNAVAILABLE` error into more specific error codes when possible, introducing the new codes `INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED`, `INSUFFICIENT_TRANSACTION_DATA`, and `DATA_QUALITY_CHECK_FAILED`. Also replaced `INVALID_FIELD` with `NETWORK_CONSENT_REQUIRED` for the use case where the end user has not given consent to share network data. For details on these new codes, as well as improved documentation of existing codes, see [Check Report Errors](https://plaid.com/docs/errors/check-report/index.html.md) .
*   Improved the sensitivity of the `CHECK_REPORT_FAILED` webhook at alerting to partial failures. Previously, certain types of partial Check Report failures would not trigger the webhook.
*   Added `successful_products` and `failed_products` arrays to the `CHECK_REPORT_READY` webhook to provide more granular detail on partial Check Report failures.
*   Plaid can now pre-fill a user’s phone number in Link using information from the `consumer_report_user_identity` object if the phone number is not pre-filled via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Pre-filling phone numbers can help boost conversion while reducing steps for users. Support for this feature is currently available in Production and will be added in Sandbox in the coming months.
*   Increased the speed of report generation by approximately 25%.
*   By the end of March, to improve security, Plaid will send all end users who complete the Plaid Check Link flow flow a confirmation email, similar to the change to Plaid Link announced in the [January 30 changelog entry](https://plaid.com/docs/changelog/index.html.md#january-30-2025) .

For Signal:

*   Added realtime backtesting support to the Signal Dashboard.
*   Added a view-only permission to the Signal Dashboard.

##### March 17, 2025 

*   Released split billing: For certain products, customers on a single client ID can now split their API usage across cost centers via API headers. To learn more, contact your Plaid Account Manager or see [Setting cost centers](https://plaid.com/docs/account/billing/index.html.md#setting-cost-centers) .
*   SAML is now available as a method of user access management for the Dashboard to customers on Plus or Premium Support packages.

For Link:

*   Released iOS SDK 6.1.0, with improvements to Remember Me Silent Network Authentication.
*   Released React Native SDK 12.0.3, which updates to iOS SDK 6.1.0.

For Auth and Transfer:

*   Announced the impending migration of US Bank to tokenized account numbers (TANs), scheduled to occur May 2025.

For Identity:

*   Added support for API-based detection of pass / fail results from Identity Match sessions when Identity Match rules are configured via the [Dashboard](https://dashboard.plaid.com/account-verification) via the `IDENTITY_MATCH_PASSED` and `IDENTITY_MATCH_FAILED` Link events.

For Layer:

*   Publicly documented [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) as the preferred endpoint for creating a Layer session, rather than [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , and added `redirect_uri` support to [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) .

For Plaid Check Consumer Reports:

*   Added support for `client_report_id` to Income Insights Reports. Moved `client_report_id` field to the top-level [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) request, rather than being inside the `base_report` request object, to reflect that the `client_report_id` is no longer Base Report-specific. Usage of the `client_report_id` within the `base_report` object is deprecated.
*   Changed the `score` field from a float to an integer in the API spec, to reflect that it will always be an integer.

For Statements:

*   Added `posted_date` field to [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) response.

##### March 1, 2025 

For Auth:

*   Added the ability to configure micro-deposit and database verification-based Auth flows via the [Dashboard](https://dashboard.plaid.com/account-verification) .
*   Marked Database Match and Database Insights (beta) as deprecated in favor of the new Database Auth feature, which provides functionality similar to Database Insights. These features are still available, but customers should plan to migrate to Database Auth when possible.

For Identity:

*   Added the ability to configure Identity Match rules via the [Dashboard](https://dashboard.plaid.com/account-verification) when using Identity and Auth as the only products.

For Plaid Check Consumer Report:

*   Updated behavior when calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to improve consistency. Previously, no reports would be eagerly generated upon calling this endpoint. Now, the base report will always be eagerly generated, along with products specified in the `products` array.
    
*   When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , it is now possible to include Plaid Check products within the `optional_products`, `required_if_supported_products`, or `additional_consented_products` request fields when Plaid Inc. products are included in the `products` field, or vice-versa.
    
*   Identity data is now provided in the Base Report only. Plaid will no longer return identity data in the Income and Partner Insights products, and the fields will be removed from API responses by June 30, 2025.
    
*   Removed the Cashflow Updates `INSIGHTS_UPDATED` `reason` code. Instead, a separate webhook will be fired for each reason.
    
*   The `score` field in [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) is now nullable.
    

For Transfer:

*   Added `intent_id` to the transfer event object returned by [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) , for transfers created via Transfer UI. This will currently only be populated for RfP transfers.

##### February 11, 2025 

For Link:

*   Released React Native SDK 12.0.3, which contains LinkKit 6.0.4, which fixes an issue where some sessions experienced delays in receiving the `LAYER_READY` event or did not receive it at all, and fixes an issue with XCFramework.

For Auth:

*   Improved Sandbox behavior to better reflect institutions that use Tokenized Account Numbers (TANs). In Sandbox, Chase and PNC will now return `is_tokenized_account_number: true` and have populated `persistent_account_id` fields.

For Plaid Check Consumer Report:

*   `consumer_report_user_identity.date_of_birth` is now a required field when creating or updating a user token with a `consumer_report_identity` field.
*   Completed the renaming of several fields. The `longest_gap_between_transactions`, `average_inflow_amount`, and `average_outflow_amount` fields have been removed and replaced with pluralized versions `longest_gaps_between_transactions`, `average_inflow_amounts`, and `average_outflow_amounts` fields to better reflect the fact that they are arrays.

For Signal:

*   Announced a behavior change for Items that were manually linked (e.g. using Same Day Micro-deposits or Database Insights). Beginning February 18, any Item that was manually linked but could not be given a Signal score and attributes by [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will no longer return a `PRODUCT_NOT_SUPPORTED` error. Instead, the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) call will succeed. This change allows customers to evaluate these Items using Signal Rules that do not require a Signal score and attributes. Billing will only be triggered for the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) call if either a score is returned or a Signal Rule is evaluated.

For Virtual Accounts:

*   Added `originating_fund_source` to [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) request. This field is required by local regulation for certain use cases (e.g. money remittance) to send payouts to recipients in the EU and UK.

##### February 3, 2025 

For Link:

*   Released iOS SDK 6.0.4, which fixes an issue where some sessions experienced delays in receiving the `LAYER_READY` event or did not receive it at all, and fixes an issue with XCFramework.

##### January 30, 2025 

Notified all customers that they must sign an addendum to their agreement with Plaid to retain PNC data access after February 28th, 2025. If you do not know how to sign this addendum, or are not sure if you have signed it, contact your Plaid Account Manager or Plaid Support.

For Link:

*   Released React Native SDK 12.0.1, which includes iOS SDK 6.0.2 and resolves issues where the SDK was not working with React Native 0.76 or later.
*   Released React Native SDK 12.0.2, which results an issue where the `USE_FRAMEWORKS` preprocessor check was failing for projects using `use_frameworks! :linkage => :static`.
*   To improve anti-fraud measures, began more broadly sending email confirmations to end users when they have linked an account to Plaid, allowing them to report unrecognized Link activity. Previously, Plaid would send these notifications only if the session was flagged as elevated risk.

For Payment Initiation (UK/EU):

*   Added the `end_to_end_id` field to the payment object, providing a unique identifier for tracking and reconciliation purposes.

For Transfer:

*   For [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) , added an `institution_supported_networks.rfp.debit` field to indicate an institution's support for debit request for payment (RfP).
*   Added `funds_available` sweep status and event type.

##### January 17, 2025 

SSO is now available, at no additional charge, to all customers except those on Pay-as-you-go plans. You can enable SSO via the [Dashboard > Team Settings > SSO](https://dashboard.plaid.com/settings/team/sso) .

For Link:

*   Released iOS SDK 6.0.1, with enhanced support for Silent Network Authentication in the Remember Me flow.
*   Released iOS SDK 6.0.2, with small improvements to the UI of the Remember Me flow.
*   Improved the UI for failed connection attempts at OAuth institutions to increase conversion. Rather than "Exit," the primary CTA on the Link error screen for this scenario is now a "Try Again" button that will directly re-start the institution's OAuth flow.
*   Added phone number recycling detection to Link. The returning user experience will delete a user's Returning User profile if it detects that the phone number has been reassigned to a different customer since the user's last login, reducing the risk of fraud and account takeover.

For Plaid Check:

*   Added `nsf_overdraft_transactions_count_30d/60d/90d` fields to `attributes` field of [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) .

For Payment Initiation:

*   Added [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) endpoint to improve ease of testing in Sandbox.

For Signal:

*   [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) now supports creating rules based on the results of a [Database Insights](https://plaid.com/docs/auth/coverage/database/index.html.md) check.

For Transfer:

*   Added Transfer Rules, allowing you to customize the logic used by the Transfer Risk Engine during the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call. You can configure your [Transfer Rules](https://dashboard.plaid.com/transfer/risk-profiles) via the Dashboard.
*   To better represent errors from a variety of payments rails beyond just ACH, added `failure_code` and `description` fields to [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) and `transfer/sweep/list` endpoints. Developers should use these instead of of the `ach_return_code` field.

##### January 2, 2025 

For Link:

*   For institutions such as PNC, Chase, and Charles Schwab that previously invalidated Items when a duplicate Item was added, prevented the old Item from becoming invalidated unless either Item is initialized with a Plaid Check product or the two Items have different sets of accounts associated. This is a delayed announcement of a change made in April 2024.
*   Released React Native SDK 12.0.0. This incorporates iOS SDK 6.0.0 and Android SDK 5.0.0. Major updates include adding support for FinanceKit and AppleCard on iOS, removing the deprecated `PlaidLink` component and `openLink` function, and updating a number of Android libraries. For a full list of all changes in this release, see the [Release notes](https://github.com/plaid/react-native-plaid-link-sdk/releases/tag/v12.0.0) .

##### December 23, 2024 

For Link:

*   Released Android SDK 5.0.0, containing numerous library and platform updates, including upgrading Kotlin to 1.9.25, and upgrading the compile version to SDK 35. This SDK version also adds the `AUTO_SUBMIT` event name and `INVALID_UPDATE_USERNAME` Item error, removing the `PROFILE_ELIGIBILITY_CHECK_ERROR` event name. For a full list of all libraries updated in this SDK release, see the [Release notes](https://github.com/plaid/plaid-link-android/releases/tag/v5.0.0) .

##### December 17, 2024 

For Auth:

*   PNC now supports the `USER_ACCOUNT_REVOKED` and `USER_PERMISSION_REVOKED` webhooks, allowing you to reduce return risk. Upon receiving either of these webhooks, Auth customers should no longer make ACH transfers using the tokenized account numbers of the associated Items.

For Transactions:

*   For the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, added the ability to use an `account_id` filter.

##### December 13, 2024 

For Plaid Check:

*   Began the rollout of Plaid Passport, an update to the Plaid Check bank linking flow. Plaid Passport is an extension of the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) specific to Plaid Check, and will enable conversion efficiencies across all financial institutions, improved Item health, and enhanced user-centric insights. You do not need to take any action to enable Plaid Passport.

##### December 10, 2024 

For Link:

*   Released [React Native SDK 11.13.3](https://github.com/plaid/react-native-plaid-link-sdk) , fixing a regression introduced in version 11.13.1 that caused build failures for some customers.
*   Completed the rollout of Passkey support for the returning user experience in Link to all eligible sessions. Passkey support increases security and provides a more streamlined experience for returning users. With Passkeys, end users on iOS devices who have previously logged in to a financial account through Link can opt in to using Face ID or Touch ID to authenticate to this account for subsequent Link sessions. To enable Passkey support, ensure you are using the Plaid iOS SDK 4.3.0 or later or the Plaid React Native SDK 10.2.0 or later. You do not need to take any other action to enable Passkey support.

##### December 4, 2024 

*   Added `institution_name` to the `Item` object schema. You no longer have to call [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) to translate the institution data in an Item to human-readable format.
*   For [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) , added support for `USER_PERMISSION_REVOKED` and `USER_ACCOUNT_REVOKED` webhooks.

For Link:

*   Increased the rollout of Passkey support for the returning user experience in Link. Passkey support increases security and provides a more streamlined experience for returning users. With Passkeys, end users on iOS devices who have previously logged in to a financial account through Link can opt in to using Face ID or Touch ID to authenticate to this account for subsequent Link sessions. Passkey support will be rolled out to all eligible sessions by the end of the year. To enable Passkey support, ensure you are using the Plaid iOS SDK 4.3.0 or later or the Plaid React Native SDK 10.2.0 or later. You do not need to take any other action to enable Passkey support.
*   Added biometric authentication support for Citibank on Android (biometric authentication support for Citibank on iOS was added in June 2024). No SDK update is required.
*   Released Plaid Link for React Native SDK 11.13.2, updating Android Compile Version from 31 to 34.

For Auth:

*   Added `is_tokenized_account_number` field to [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to indicate whether an account number is tokenized. Tokenized account numbers may require special business logic to avoid ACH returns. For more details, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) .
*   Added support for cash management account subtypes, rather than just checking and savings.
*   Added `auth_method` enum to the `Item` object schema to indicate which verification method (e.g. Instant Auth, Same-Day Micro-deposits, Database Match...) was used to verify the Item.
*   Added `SAME_DAY_MICRODEPOSIT_AUTHORIZED` and `INSTANT_MICRODEPOSIT_AUTHORIZED` transition view names to Link.

For Plaid Check Consumer Reports:

*   Added the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) endpoint to facilitate testing.
*   Enhanced the model used for estimating gross income from net income, resulting in ~10% greater accuracy.
*   Users with the Team Management permission can now download a copy of their submitted Plaid Check application form from the Dashboard under Settings > Compliance Center > Company Documents.

For Identity Verification:

*   At the start of the Selfie Check flow, added a warning to users if insufficient ambient light is detected, prompting them to fix their lighting conditions before proceeding.

For Investments:

*   For the `security` object, added the `fixed_income` object with the following details: `yield_rate`, `maturity_date`, `issue_date`, and `face_value` fields, to provide additional details on bonds and other fixed income securities.
*   Added processor partner support for Investments with the new [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) and [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) endpoints.

For Transfer:

*   Added support for cash management account subtypes, rather than just checking and savings.
*   Added `auth_method` enum to the `Item` object schema to indicate which verification method (e.g. Instant Auth, Same-Day Micro-deposits, Database Match...) was used to verify the Item.
*   Added `SAME_DAY_MICRODEPOSIT_AUTHORIZED` and `INSTANT_MICRODEPOSIT_AUTHORIZED` transition view names to Link.
*   Added `webhook` field to requests for [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) , [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) , [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) and [/sandbox/transfer/sweep/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersweepsimulate) .
*   Added `funds_available` support for [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) .

##### November 14, 2024 

*   Released [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) to help customers obtain consent logs for auditing purposes.
*   Added consent related-details to the `item` object in [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) , including `consented_data_scopes`, `consented_use_cases`, and `consent_expiration_time`, to help customers manage consent records and consent expiration.

For Link:

*   Released Plaid Link for iOS SDK 6.0.0, introducing FinanceKit and support for Apple Card integration.
*   Released Plaid Link for React Native SDK 11.13.1, fixing a compiler error when using the New Architecture with Expo.

For Assets:

*   Added a hard limit of 15,000 transactions per Asset Report, to avoid returning truncated Asset Reports. An Asset Report with more than 15,000 transactions will now trigger the error `ASSET_REPORT_GENERATION_FAILED` with an error message "asset report is too large to be generated, try again with a shorter date range".

##### November 7, 2024 

For Link:

*   Released Plaid Link for React SDK 3.6.1, fixing an issue that can occur when unmounting the `usePlaidLink` hook before the underlying script tag is loaded.
*   Customers can now self-enable for [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) without contacting their Account Manager. To enable Hosted Link, provide a `hosted_link` object in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. The object can be empty or can include configuration parameters for Hosted Link. This change does not apply to Link Delivery, which still requires Account Manager enablement.

##### October 29, 2024 

For Link:

*   Added support for Vietnamese and Hindi.
*   Added `AUTO_SUBMIT_PHONE` event to capture scenarios where the user's phone number is supplied in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call and the user has previously enrolled in the returning user experience, allowing Plaid to send an OTP code without prompting.
*   Improved conversion through improved error messaging for incorrect username / password at non-OAuth institutions. Previously, users would be taken to an error pane and required to press the back button to retry their credentials; the new UI provides inline error messages if the user's credentials are incorrect.
*   Fixed bug in which users could enter an error state by clicking a button while the in-progress spinner was active on a different button.
*   Minor improvements to consistency in font weight and styling.

For Consumer Report by Plaid Check:

*   For the endpoint [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , added the `total_inflow_amount` and `total_outflow_amount` objects, with corresponding objects `total_inflow_amount_30d`, `total_inflow_amount_60d`, `total_inflow_amount_90d`, `total_outflow_amount_30d`, `total_outflow_amount_60d`, and `total_outflow_amount_90d`, to summarize inflows and outflows.
*   For Partner Insights Reports, deprecated the `version` field (which used type `number`) and replaced it with the `model_version` field (which uses type `string`), to better support the not-strictly-numerical versioning scheme used by Prism.

For Identity Verification:

*   For the response bodies of the endpoints [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) , [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) , and [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) , added the `verify_sms` object. This object contains details about SMS verification attempts, with sub-fields such as `status`, `attempt`, `phone_number`, `delivery_attempt_count`, `solve_attempt_count`, `initially_sent_at`, `last_sent_at`, and `redacted_at`.
*   Restored the "Integration" button to the Dashboard. It can now be found next to the "Publish Changes" button in the upper right of the Template Editor.

For Payment Initiation:

*   For [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) , added `payer_details` object. The fields `options.bacs` and `options.iban` have been deprecated in favor of `payer_details.numbers.bacs` and `payer_details.numbers.iban`; customers are encouraged to migrate to the new fields.

For Signal:

*   Made the `scores` field nullable in the responses for [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) and [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) , as a pre-requisite for adding future Signal support to Items where a score cannot be calculated, such as Items added via Database Insights or Same-Day Micro-deposits.
*   Changed Signal billing to behave similarly to Auth and Identity if it is specified in the `optional_products` array -- customers will not be billed for Signal if it is specified in `optional_products` until [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is called.

##### October 28, 2024 

*   Fully removed legacy returning user flows (Institution Boosting, Pre-Matched RUX, and Pre-Authenticated RUX) in favor of the new returning user experience.
*   Removed legacy returning user flow errors, `INVALID_PRODUCTS` and `PRODUCT_UNAVAILABLE`.

##### October 15, 2024 

*   For the `PENDING_DISCONNECT` webhook, added `INSTITUTION_TOKEN_EXPIRATION` as a `reason` code. This reason will be used if the user's access-consent on an OAuth token is about to expire. This webhook code will only be used for Items associated with institutions in the US and Canada; for Items in the UK and EU, Plaid will continue to send the `PENDING_EXPIRATION` webhook instead of the `PENDING_DISCONNECT` webhook in the event of pending OAuth access expiration.

For Plaid Check Consumer Reports:

*   Reverted the change to historical balance data from the October 11 update. Updated the documentation to clarify the behavior and reduce customer confusion.
*   Added `attributes` object with fields `nsf_overdraft_transactions_count`, `is_primary_account`, and `primary_account_score` to Base Report object, to help identify primary accounts and overdraft transactions.

For Payment Initiation:

*   For the `/payment_initiation/consent/*` endpoints, deprecated the `scopes` field in favor of the `type` field, with possible values `SWEEPING` or `COMMERCIAL`. The `scopes` field will still be honored if used, but customers are encouraged to use the new `type` field instead, and the `scopes` field will be removed in the future.

##### October 11, 2024 

For Plaid Check Consumer Reports:

*   For [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , added the fields `last_4_ssn` and `date_of_birth` to the `consumer_report_user_identity` object. All user tokens created after January 31, 2025 must have a `date_of_birth` populated in order to be compatible with Plaid Check Consumer Reports.
*   Changed the behavior of returning historical balances. Previously, Consumer Reports would always return at least 90 days of historical balance information. This caused user confusion in the case of new accounts opened less than 90 days ago, since Consumer Report would report a historical balance on the account for dates when the account did not yet exist. Now, Consumer Reports will only return historical balances up to the date of the oldest transaction found in a given account.
*   Released Cash Flow Updates and Network Insights to beta. For details, see [Plaid Check](https://plaid.com/docs/check/index.html.md#overview) .

For Identity Verification:

Introduced several updates to Identity Verification. These changes are being gradually rolled out to customers. To request to be opted in to these changes early, or to delay receiving these changes, contact your Plaid Account Manager.

*   Introduced Trust Index, a numerical scoring system rating the user on a scale of 1 to 100, with 11 sub-scores on different dimensions (e.g. email, phone, liveness), to help you understand users' relative risk across various dimensions and how different factors contribute to that risk.
*   An overhauled session view that helps you digest a full user's verification without scrolling.

For Income:

*   Fixed an issue in which customers could successfully call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for Income without specifying a `user_token`. The `user_token` field is required when using Income.

##### October 9, 2024 

*   Began the automatic enrollment of some customers into [Data Transparency Messaging (DTM)](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . Throughout Q4, customers serving end users in the US and Canada will be enrolled in DTM automatically if they have not already enrolled.
*   Announced the elimination of public key support, effective January 31, 2025. Beginning in February 2025, it will no longer be possible to launch Link sessions using a public key. This impacts only a small number of customers, as the Plaid public key has been deprecated since the introduction of Link tokens in mid-2020, and no teams created after July 2020 have been issued public keys. All customers who are still using public keys were notified of this change via email in September. For instructions on migration from public keys to Link tokens, see the [Link token migration guide](https://plaid.com/docs/link/link-token-migration-guide/index.html.md) .
*   Announced the full removal of legacy returning user flows (Institution Boosting, Pre-Matched RUX, and Pre-Authenticated RUX) in favor of the new returning user experience, to be completed by October 28, 2024.
*   Eligible customers (those with support packages) can enroll in SSO via the [Dashboard](https://dashboard.plaid.com/settings/team/sso) . If you would like to use SSO and do not have a support package, contact your Plaid account manager.
*   To reduce developer confusion, updated the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint to return the various results arrays and objects (`item_add_results`, `payroll_income_results`, `document_income_results,` `bank_income_results`, `cra_item_add_results`) as empty arrays (if arrays) or as null (if objects) when not present, rather than being omitted from the schema.

For Link:

*   Improved the user experience for Remember Me verification on eligible Android devices by automatically filling in the OTP code received on the device.

For Auth:

*   PNC now returns Tokenized Account Numbers (TANs) with behavior similar to Chase.

For Balance:

*   Discontinued the Balance Plus beta program. Balance Plus beta will no longer accept new enrollments; customers currently in the beta program have been contacted directly with more details and next steps.

For Plaid Check Consumer Report:

*   Released the Plaid Check Third-Party User Token to beta, allowing customers to partner with select lenders to provide their customers access to credit. If you are interested in this feature, contact sales or your Plaid Account Manager.
    
*   Integrated Plaid Check Consumer Reports with Layer to enable users to share cash flow insights alongside identity and bank data instantly, dramatically streamlining the loan application process. Users consent to share their consumer report in the final Layer pane. If you are interested in this feature, contact sales or your Plaid Account Manager.
    
*   Updated the [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) endpoint transaction history behavior for new customers. If no value is specified for the `days_requested` field, Plaid will default to requesting 365 days, and if a value under 180 is specified, Plaid will request 180 days. This change increases the quality of transaction history insights, as the more transaction history is requested, the more accurate the insights returned will be. This change impacts only customers obtaining Plaid Consumer Report Production access on or after October 1, 2024; the behavior for existing customers will not change.
    
*   In the [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) response `warnings` array, added a new possible warning code, `USER_FRAUD_ALERT`, which indicates that the user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud.
    
*   For the [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) endpoint, added an `error_reason` to the response to surface Prism error codes.
    

For Identity:

*   Released [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) to beta. Identity Document Upload provides document-based account ownership identity verification for Items that do not support [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) or [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , including Items connected via Same-Day Micro-deposits or Database Insights.

For Identity Verification:

*   Redesigned the fraud labeling system UI to allow 1-click fraud reports from the Dashboard.
*   Fixed ordering of Link events callbacks when Hide Verification Outcome is enabled so that `IDENTITY_VERIFICATION_CLOSE_UI` fires and `onSuccess` is called after the event corresponding with the outcome of the session has fired.

For Layer:

*   Integrated Plaid Check Consumer Reports with Layer to enable users to share cash flow insights alongside identity and bank data instantly, dramatically streamlining the loan application process. Users consent to share their consumer report in the final Layer pane. If you are interested in this feature, contact sales or your Plaid Account Manager.

For Payment Initiation:

*   For [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) endpoint, added the optional `processing_mode` parameter. This allows you to opt in to async payment execution processing, allowing for better performance and throughput when realtime payment processing results are not necessary, such as in user-not-present flows.

For Transfer:

*   Improved [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) to consider more information about accounts, such as whether the account has previously returned codes R02 (account closed) or R16 (account frozen) when used with Plaid.

##### September 2024 

*   Released [Link Recovery](https://plaid.com/docs/link/link-recovery/index.html.md) to beta. With Link Recovery, your end users can sign up to be automatically notified by Plaid when an institution outage that prevented them from linking an account has been resolved. When the issue is over, Plaid will send users a link that can be used to connect their account to your app.
    
*   Released [Investments Move](https://plaid.com/docs/investments-move/index.html.md) to Early Availability. Investments Move facilitates ACATS and ATON brokerage transfers by providing user-permissioned data including a user's account number, account information, and detailed holdings information. Investments Move can remove friction for end users in changing brokerages and reduce the frequency of transfer failures caused by data entry errors.
    
*   Improved retry logic for missed webhooks. If a webhook sent by Plaid is not accepted by the webhook receiver endpoint with a `200` status within 10 seconds of being sent, Plaid will now retry up to six times over a 24-hour period, using an exponential backoff algorithm, rather than the previous behavior of retrying up to twice, a few minutes apart.
    
*   Added a new `PENDING_DISCONNECT` Item webhook to alert customers of Items that are about to enter an unhealthy state. Unlike the existing `PENDING_EXPIRATION` webhook, `PENDING_DISCONNECT` covers Items that will break due to reasons other than consent expiration, such as a planned sunset by the bank of an old online banking platform, or a required migration to OAuth. Upon receiving a `PENDING_DISCONNECT` webhook, customers should direct the end user to the update mode flow for the Item.
    
*   Added the ability to use update mode to reauthorize consent for a US or CA Item whose consent is expiring due to 1033 rules. If the consent expiration date is within 6 months, Plaid will automatically route the Item through the longer reauthorization update mode flow, which will cause the expiration date to be pushed to 12 months from the date that the user reauthorizes the Item. You can customize whether or not the Item goes through the reauthorization update flow by using the `update.reauthorization_enabled` parameter in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Note that there is no reason to send Items through the reauthorization flow at this time, as Items will not be assigned consent expiration dates until approximately December 2024. This change only impacts Items in the US and Canada; the OAuth update flow for Items in the UK and EU has not changed.
    
*   To help manage consent status for the upcoming wider Data Transparency Messaging rollout, added `consented_use_cases`, `consented_data_scopes`, and `created_at` fields to the Item object.
    
*   Removed `deposit_switch` from the `products` array, as part of Deposit Switch deprecation.
    

For Link flow:

*   Shortened and clarified text shown to end user during prompt to verify 2FA code.
*   Added hover animations to UI buttons in Link.

For Plaid Link SDKs:

*   Released iOS SDK 5.6.1, which adds adds haptics support, fixes embedded search view dynamic resizing, and adds missing event names and view names. For details, see the [iOS SDK changelog](https://github.com/plaid/plaid-link-ios/releases) .
*   Released Android SDK 5.6.1, which adds missing event names and view names. For details, see the [Android SDK changelog](https://github.com/plaid/plaid-link-android/releases) .
*   Released React Native SDK 11.13.0, which incorporates iOS SDK 5.6.1 and Android SDK 4.6.1. For details, see the [React Native SDK changelog](https://github.com/plaid/react-native-plaid-link-sdk/releases) .

For Assets:

*   Added [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) request parameter `options.require_all_items`, with a default value of `true`. By setting this to `false`, customers can optionally choose to generate an Asset Report even if one or more Items in the Asset Report encounters an error, as long as at least one Item succeeded. Otherwise, the endpoint will maintain its current behavior of only creating an Asset Report if all Items could be successfully retrieved.

For Consumer Report:

*   Fixed confusing pluralization by renaming `longest_gap_between_transactions` to use `gaps` rather than `gap` as this field is array of gaps rather than a single gap. The old version of this field is deprecated and will be removed at the end of October.
*   Removed the `products` field from the [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) request, as its usage there is deprecated.

For Identity Verification:

*   Added `liveness_check` results to [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) to improve parity between API and Dashboard data availability.
*   Added `name` object to the `extracted_data` within each `documentary_verification.documents` object in the response of all of the Identity Verification endpoints.
*   Design updates to the Identity Verification Dashboard.

For Investments:

*   Added `sector` and `industry` fields to the securities object to help categorize holdings.

For Transfer:

*   Updated [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) to accept either a `transfer_id` or a `transfer_authorization_id`.
*   In [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) request, replaced `from_client_id` and `to_client_id` with `from_ledger_id` and `to_ledger_id`.

##### August 2024 

*   Added [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) , which allows end users to link multiple financial accounts in a single Link session.
*   Added the `error_code_reason` field to the Plaid error object to provide more useful troubleshooting details for `ITEM_LOGIN_REQUIRED` errors at OAuth institutions. This field is currently in beta and may not be present for all customers.
*   Added the ability to launch update mode with a user token and augmented [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with an `update.item_ids` field to optionally specify which Item ID(s) to update when launching Link in update mode with a user token. Launching update mode with a user token is the only supported update mode flow for Consumer Report. For products that use both access tokens and user tokens, like Income, update mode can be launched using either one.

For Plaid Link SDKs:

*   Released an alternative installation repo to reduce download sizes for projects using Swift Package Manager. For details, see the [iOS SDK changelog](https://github.com/plaid/plaid-link-ios/releases) .
*   Released Android SDK 4.6.0, with dependency updates and improved Java compatibility. For more details, see the [Android SDK changelog](https://github.com/plaid/plaid-link-android/releases) .
*   Released React Native 11.2.1, with enhanced support for React Native New Architecture, and including upgrades to Android SDK 4.6.0 and iOS SDK 5.6.1. For more details, see the [React Native SDK changelog](https://github.com/plaid/react-native-plaid-link-sdk/releases) .

For Plaid Link:

*   The password input boxes in Link now allow the user to optionally reveal the password before submitting their credentials, in order to help reduce typos in password data entry.

For Beacon (beta):

*   Added data breach reporting.

For Plaid Check Consumer Reports:

*   Added a `consumer_disputes` field to the response for [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , showing the details of any disputes the consumer has submitted about the information in the report.

For Identity Verification:

*   Added `is_shareable` parameter to [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) to allow configuring different retry behavior for the original session and retry sessions. If set, this parameter will control whether a shareable link is generated for the retry session. If not set, the retry session will use the same shareable link behavior as the original session.

For Income:

*   Added `file_type` field to [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) .
*   Added the ability to customize the `ytd_amount` field in the Sandbox custom user for [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) .

For Investments:

*   Added Investments Refresh. Investments Refresh is available as an add-on to Investments and allows you to make a real-time, on-demand update request for fresh Investments data by calling the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint.

For Liabilities:

*   Plaid has discontinued support for federal student loan providers: Aidvantage, Central Research, Inc., EdFinancial Services - Federal Direct Loan Program (FDLP), Mohela and NelNet. Beginning in September, Liabilities subscriptions on Items from these institutions will no longer be billed, and end users will not be able to select these institutions in Link. Private student loan providers are not impacted. Impacted customers have been contacted directly by their Account Managers. For questions, contact your Plaid Account Manager.

For Transfer:

*   Added support for multiple Ledgers. This improves the Plaid Transfer experience for customers who need to avoid co-mingling funds from different types of sources. As part of this change, several Transfer endpoints now have the optional ability to specify a `ledger_id` in the request and/or will return a `ledger_id` as part of the response. To request multiple Ledgers, contact your Plaid Account Manager.
*   Improved the flow for authorizations that could not be evaluated due to the `ITEM_LOGIN_REQUIRED` error by enabling [update mode](https://plaid.com/docs/link/update-mode/index.html.md) for these authorizations, allowing them to be retried after the Item is fixed. Authorizations that previously would have had an `approved` decision and a `rationale_code` of `ITEM_LOGIN_REQUIRED` will now have the new `user_action_required` decision instead. If [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) returns an `user_action_required` decision, you can now launch Link in update mode by creating a Link token with the `authorization_id` passed to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . After the end user has completed the update mode flow, you can retry the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call.
*   For [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) , added an [authorization\_usage](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) response object allowing you to see your credit and debit utilization details.

For Virtual Accounts:

*   Added the `related_transactions` array to the Wallet transaction object. This field makes it easier to identify associated transactions by showing the transaction ID of related transactions, as well as how they are related. For example, if a transaction is refunded, the original transaction and the refunded transaction will be linked via the `related_transactions` field.

##### July 2024 

*   Added support for Silent Network Auth (SNA) for the Android returning user experience. SNA is a faster and more secure method to verify an end user's phone number. To use SNA, you must be using at least version 3.14.3 or later of the Android SDK (if using 3.x) or version 4.1.1 or later (if using the 4.x). On React Native, the corresponding minimum versions are 10.12.0 and 11.4.0. Aside from updating your SDK, no action is required to enable SNA.
*   Added support for biometric authentication for Citibank for integrations using the iOS SDK version 5.1.0 or later.
*   Released account holder category (beta), indicating whether an account returned in the account object is a business or personal account. To request access to this feature, contact your account manager.

For Plaid Link SDKs:

*   Released Android SDK 4.6.0, containing bug fixes and compatibility improvements. For details, see the [Android SDK changelog](https://github.com/plaid/plaid-link-android/releases) .

For Auth:

*   Released [AUTH: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#default_update) webhook to GA. This webhook fires if Plaid detects that a bank's Auth information has changed. (While rare, this can occur due to changes such as an acquisition.) To avoid ACH returns, after receiving this webhook, you should call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) to update your information on file for the user.

For Identity:

*   In [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , `legal_name.is_business_name_detected` is no longer deprecated and can now be used for detecting business names.

For Transfer:

*   Added [return\_rates](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfer-metrics-get-response-return-rates) field to [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) , allowing you to get return rate information via the API.

##### June 2024 

*   Launched [Plaid Layer](https://plaid.com/docs/layer/index.html.md) to early availability. Layer provides a fast, high-converting onboarding experience powered by Plaid Link.
*   Launched [Plaid Check](https://plaid.com/docs/check/index.html.md) , a subsidiary of Plaid Inc. that is a Consumer Reporting Agency. Through Plaid Check's Consumer Report API, you can retrieve ready-made credit risk insights from consumer-permissioned cash flow data.
*   Decommissioned the Development Environment. Development has been replaced for testing purposes by Limited Production. For more details, see [Limited Production](https://plaid.com/docs/sandbox/index.html.md#testing-with-live-data-using-limited-production) .

For Plaid Link SDKs:

*   Released iOS SDK 5.6.0, containing support for Plaid Layer, as well as bug fixes and improvements to the returning user experience.
*   Released iOS SDK 4.7.9, containing bug fixes and improvements to the returning user experience.
*   Released Android SDK 4.5.0, containing support for Plaid Layer, as well as bug fixes.
*   Released React Native 11.11.0, containing support for Plaid Layer, as well as bug fixes and improved prefill support.

For Beacon:

*   Added `access_tokens` field to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) and [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) requests.
*   Added `item_ids` to `/beacon/user/*` responses.
*   Added Bank Account Insights to Beacon. Account Risk (beta) is being folded into Beacon

For Balance:

*   Launched Balance Plus (beta). Balance Plus enhances Plaid's Balance product with additional insights and lower latency and is designed to require minimal integration work for existing Balance customers.

For Income:

*   Launched [Plaid Check](https://plaid.com/docs/check/index.html.md) , a subsidiary of Plaid Inc. that is a Consumer Reporting Agency. Through Plaid Check's Consumer Report API, you can retrieve ready-made credit risk insights from consumer-permissioned cash flow data.
*   Added [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) to support the deletion of user tokens.

For Liabilities:

*   Added `income-sensitive repayment` as a student loan repayment type.

For Transactions:

*   As originally announced in the November 2023 changelog, the default number of days of transactions history requested for new transactions-enabled Items is now 90 days for all customers. To change this behavior, use the `days_requested` parameter in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or (if initializing transactions post-Link) [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .
*   Improved behavior of Transactions-enabled Items being fixed via update mode. Now, if an Item was in an error state for over 24 errors before entering update mode, Plaid will immediately extract fresh transactions after update mode has completed, rather than waiting for the next scheduled update time.

For Transfer:

*   Added support for RTP to Transfer UI.
*   Added improved support for Transfer limit increase requests via the Transfer Dashboard.

For Virtual Accounts:

*   Added support for `RECALL` as a transaction type where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment.

##### May 2024 

*   Released [Limited Production](https://plaid.com/docs/quickstart/glossary/index.html.md#limited-production) , which will replace Development as a platform for testing for free with live data. The Development environment will be decommissioned on June 20, 2024, and all Development Items will be deleted.
*   Released [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) to GA. To help ensure compliance with 1033 rulemaking, DTM will be automatically enabled for US and CA Link sessions later this year.
*   Added new pre-seeded Sandbox test accounts for testing different credit profiles. These accounts are especially useful for testing Income, but are available to all customers. For details, see [Credit and Income testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) .
*   Updated the response object for [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . To accommodate future multi-Item Link session support for additional products, the `on_success` object in the response has been deprecated; it is recommended to use the new `results` object instead. Old: `link_sessions[0].on_success.public_token`. New: `link_sessions[0].results.item_add_results[0].public_token`. The `on_exit` field has also been deprecated; it is recommended to use the new `exit` field.
*   Updated the `SESSION_FINISHED` webhook. To accommodate future multi-Item Link session support for additional products, deprecated the `public_token` field in lieu of a new `public_tokens` array.

For Plaid Link SDKs:

*   Released iOS SDK 5.5.0 and 4.7.7, containing bug fixes and (for iOS SDK 5.5.0) additional view names to support new functionality.
*   Released iOS SDK 6.0.0 beta, containing support for Apple Card and FinanceKit.
*   Released Android SDK 4.4.1, containing bug fixes and UI improvements.
*   Released React Native SDK 11.10.1, with improved support for "pre-loading" Link for a lower-latency user experience.
*   Released React Native SDK 12.0.0 beta, containing support for Apple Card and FinanceKit.

For Income:

*   Added new values to `canonical_description` in [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) : `RETIREMENT`, `GIG_ECONOMY`, and `STOCK_COMPENSATION`.

For Signal:

*   Added support for some Items added via Same Day Micro-deposits or Instant Micro-deposits.

For Transfer:

*   Added [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) endpoint.

##### April 2024 

*   Updated [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) response to include `user_token`.
*   Rebranded Remember Me as returning user experience.

For Plaid Link SDKs:

*   Released Android SDK 4.3.1, iOS SDK 4.5.2, and React Native SDK 11.8.2, containing bug fixes and UI enhancements.

For Auth:

*   Released Database Match, which enables instant manual account verification using Plaid's database of known account numbers. When provided as an alternative to Same Day Micro-deposits, Database Match can increase conversion, as the user may be able to verify instantly, without having to return to Plaid to verify their micro-deposit codes.
*   Released [Database Insights (beta)](https://plaid.com/docs/auth/coverage/database/index.html.md) . Database Insights can be used as a manual alternative to credential-based Auth flows in low-risk use cases. Database Insights verifies account and routing numbers by checking the information provided against Plaid's known account numbers. If no known account number is found, Database Insights checks the information given against usages associated with the given routing number. For more information and to request access to the beta, see the [Database Insights (beta) documentation](https://plaid.com/docs/auth/coverage/database/index.html.md) .
*   Added support for the `SMS_MICRODEPOSITS_VERIFICATION` webhook to [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) to support testing the [Text Message Verification flow](https://plaid.com/docs/auth/coverage/same-day/index.html.md#using-text-message-verification) .

For Income:

*   Added the ability to customize test data in the Sandbox environment for use with Document Income, by uploading a special JSON configuration object during the document upload step. For details, see [Testing Document Income](https://plaid.com/docs/income/document-income/index.html.md#testing-document-income) .

For Payment Initiation:

*   Added `supports_payment_consents` field to an institution's Payment Initiation metadata object.
*   Added counterparty date of birth and address as optional request fields for [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) . Providing these fields increases the likelihood that the recipient's bank will process the transaction successfully.

For Statements:

*   Released [Statements](https://plaid.com/docs/statements/index.html.md) to General Availability.
*   Added Statements support to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) .

For Transfer:

*   Updated the possible values for `network` in recurring transfer contexts to reflect the fact that recurring transfers now support RTP.
*   Added `funds_available` transfer status and transfer event type.
*   Deprecated the `/transfer/balance/get` endpoint in favor of the Plaid Ledger.

##### March 2024 

For Plaid Link SDKs:

*   Multiple improvements to the Remember Me experience.
*   Added the ability to "pre-load" Link for a lower-latency user experience.

For Auth:

*   Enabled [Text Message Verification](https://plaid.com/docs/auth/coverage/same-day/index.html.md#using-text-message-verification) flow for Same-Day Micro-deposits by default. This new, non-breaking change can increase conversion of micro-deposit verification by up to 15%. This flow is now enabled for all Same Day Micro-deposit flows by default; to opt-out, use the `auth.sms_microdeposits_verification_enabled: false` setting when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

For Transactions:

*   Multiple improvements to the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint addressing common pain points:
    *   [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) now returns the `accounts` array, eliminating the need for a separate call to [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) .
    *   [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) now returns a `transactions_update_status`, reflecting the status of the transaction pulls, which was previously only available via webhook.
    *   The list of `removed` transactions now includes the `account_id`s they were associated with, to make reconciliation and management easier.
*   Granted all customers self-serve access to the `original_description` field. To access original transaction descriptions, set `options.include_original_description` to `true` when calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . It is no longer necessary to request access from your Account Manager.
*   Made `account_id` optional in the [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint.

For Transfer:

*   Added `has_more` field to [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) and [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) to indicate there are more events to be pulled.
*   Updated the possible values for `network` in recurring transfer contexts to reflect the fact that recurring transfers are only supported via ACH.

For Processor Partners:

*   Added `institution_id` to [/processor/account/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoraccountget) endpoint.

##### February 2024 

For Auth:

*   Released the [Text Message Verification](https://plaid.com/docs/auth/coverage/same-day/index.html.md#using-text-message-verification) flow for Same-Day Micro-deposits. This new, non-breaking change can increase conversion of micro-deposit verification by up to 15%. Currently, Text Message Verification is opt-in, and will transition to opt-out in March.

For Identity Verification:

*   Added a large number of additional `linked_services` enum values.

For Investments:

*   Added `vested_quantity` and `vested_value` fields to the `holdings` object.

For Liabilities:

*   Added the `pending idr` status for student loans to reflect loans with a pending application for income-driven repayments.

For Transfer:

*   Added fields including `wire_details` and `wire_routing_number`, and `wire` as a supported `network`, to support wire transfers. If you are interested in using wire transfers with Transfer, contact your Account Manager or (if you are not yet a customer) Sales.
*   Increased maximum length of `description` field on [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) from 8 to 15.

For Signal:

*   Added `warnings` array to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response even if no warnings are present in order to match documented API behavior.

##### January 2024 

*   Expanded the Returning User Link flow to more customers. For more details on the returning user experience, including the associated Link events, see [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) .
*   Added `events` field to [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to capture Link events.
*   Made the `persistent_account_id` field available in GA to all customers. The `persistent_account_id` field is a special field, available only for Chase Items. Because Chase accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify a Chase account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud.
*   Released the [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_account_revoked) webhook in GA to all customers, to complement the existing [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) webhook, but capturing account-level revocation rather than Item-level revocation. The `USER_ACCOUNT_REVOKED` webhook is sent only for Chase Items and is primarily intended for payments use cases. The webhook indicates that the TAN associated with the revoked account is no longer valid and cannot be used to create new transfers.

For Auth:

*   Added support for the Stripe Payment Intents API. For more details, see [Add Stripe to your App](https://plaid.com/docs/auth/partnerships/stripe/index.html.md) .

For Assets:

*   Added `vested_quantity` and `vested_value` fields to the Investments object within the Asset Report.
*   Added `margin_loan_amount` field to the Balance object within the Asset Report.

For Enrich:

*   Added counterparty `phone_number` to the [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) response.

For Income:

*   Added the ability to filter the results of [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) to only certain Items, via an optional `item_ids` request field.
*   Added `num_1099s_uploaded` to the `document_income_results` object in [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) response.

For Identity Verification:

*   Added new `no_data` type to `name` and `date_of_birth` fields in `documentary_verification.documents[].analysis.extracted_data` in the response of all of the Identity Verification endpoints.
*   Made `street` and `city` optional in the address attribute of [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) .

For Payment Initiation:

*   Added optional `scope` and `reference` fields to [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) .

For Transactions:

*   Added a new Sandbox test user, `user_transactions_dynamic`. When logging into Sandbox with this username, you will see more realistic, dynamic Sandbox transactions data, including a wider variety of transaction types, and transactions moving between pending and posted state.

For Virtual Accounts:

*   Added `available` balance to balance object in [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) and [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) .

For Partners:

*   Added [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) endpoint.
*   Added optional `registration_number` to [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) request.

##### December 2023 

*   Announced the upcoming removal of the Development environment. To simplify the development process, Plaid will be replacing the Development environment with the ability to test with real data for free directly in Production. On June 20, 2024, the Plaid Development environment will be decommissioned, and all Development Items will be removed. You may continue to test on the Development environment until this time.
*   Capital One now provides real-time balance data for depository accounts, including checking and savings accounts. It is no longer necessary to include `min_last_updated_datetime` when making [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) calls for these accounts.

For Investments:

*   Added `market_identifier_code` to the security object.
*   Added `option_contract` to the security object, adding additional details `contract_type`, `expiration_date`, `strike_price`, and `underlying_security_ticker` for better insight into derivatives.

##### November 2023 

For Identity:

*   Released [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and the `/identity/match/` endpoint to General Availability.

For Income:

*   Expanded [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) to support the `INCOME_VERIFICATION_RISK_SIGNALS` webhook, adding a new `webhook_code` parameter to the endpoint.

For Transfer Platform Payments (beta):

*   Added [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) endpoint, as well as a `facilitator_fee` field to [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , both of which can be used to collect payments from end customers.
*   Removed support for doc and docx format files in `/transfer/diligence/document/upload`.

For Transfer:

*   Updated default Sandbox behavior of Ledger. Ledgers in Sandbox will now have a $100 default balance.

For Transactions:

*   Added the `days_requested` field to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) and [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) under the `options` object, and to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) under the `transactions` object to support a behavior change in the Transactions product. For all new customers who created accounts after December 3, 2023 the maximum number of days of historical data requested from transactions endpoints will default to 90 days if the `days_requested` field is not specified. This change will also be applied to existing customers on June 24, 2024. To change the amount of historical data requested, use the `days_requested` field when Transactions is first added to your Item.

For Partners:

*   Added [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare)
*   Added [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget)
*   Make `products` field in `/partner/customers/create` optional. If empty or `null`, this field will default to the products enabled for the partner.

##### October 2023 

*   Chase has extended the September 30 deadline for migrating away from in-process webviews. The new cutoff date will be in mid-January 2024. All impacted customers should migrate by January 1, 2024 to avoid a negative impact on Link conversion. See the [deprecation notice](https://docsend.com/view/h3qdupjusiwyjvv5) for more details.
    
*   Added Belgium as a supported country.
    

For Auth:

*   Added an `instant_microdeposits_enabled` flag to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to allow customers to disable Instant Micro-deposits. By default, Instant Micro-deposits will be enabled for all sessions.

For Income:

*   Released Document Fraud to General Availability.
*   Added [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) , allowing users of Document Fraud to update the parsing configuration used for document income.
*   Deprecated the /credit/payroll\_income/precheck endpoint.

For Investments:

*   Added the `investments.allow_manual_entry` parameter in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and the corresponding `is_investments_fallback_item` field to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) and [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) . Enabling manual entry allows a user to create an investments fallback Item for a non-supported institution by manually entering their holdings in Link.
*   Extended the deadline beyond which Plaid customers will need a CGS license to obtain `cusip` and `isin` data. The new deadline is March 2024.

For Transactions:

*   Added `counterparties`, `logo_url`, and `website` information about merchants (previously available only via Enrich) to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) and [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) data.

For Transfer:

*   Added new methods to fund your Plaid Ledger. In addition to the [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) and [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) endpoints, you can now initiate a funds transfer via the Dashboard, set up a recurring schedule or minimum balance by contacting Support, or fund your ledger via ACH or wire transfer from your bank account.
*   Made Plaid Ledger the default method for funding transfers for all new Transfer customers. Plaid Ledger allows faster funds transfers and is now the easiest way to move money between your bank account and Plaid. Existing customers who want to switch to Plaid Ledger should contact their Plaid Account Manager.
*   Added [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) to test refunds in the Sandbox environment.
*   Added refund-specific event types. These are existing event types with the prefix `refund.`, e.g. `refund.settled`.
*   For [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) , stopped returning `max_single_transfer_amount` and `max_monthly_amount`. To maintain compatibility with older client libraries, these fields will still be present in the API, but will be blank strings.
*   For [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) , stopped returning `monthly_transfer_volume`. To maintain compatibility with older client libraries, this field will still be present in the API, but will be a blank string.

For Virtual Accounts:

*   Added `RETURN` as possible Virtual Account wallet transaction type.

##### September 2023 

*   Added the `LOGIN_REPAIRED` webhook. This webhook will fire when an Item's status transitions from `ITEM_LOGIN_REQUIRED` to a healthy state, without the user having used the update mode flow in your app.
    
*   Added [Update Mode Product Validations (beta)](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) . Update Mode Product Validations (UMPV) allows you to validate that a user going through update mode at an OAuth institution has selected the appropriate authorizations to enable Auth and/or Identity. If they do not select the correct options, they will be prompted to update their selections.
    
*   Added [Optional Products](https://plaid.com/docs/link/initializing-products/index.html.md#optional-products) . If a product is specified in the `optional_products` field when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , the product will be added to the Item if possible. However, if the product cannot be added to the Item -- for example, because the Item is not supported by the institution, the user did not grant the correct OAuth permissions, or because of an institution connectivity error for that product -- Item creation will still succeed with the other products specified.
    
*   Added `institution_not_supported` as a potential Link session exit metadata status.
    
    For Auth:
    
*   Added [Instant Micro-Deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) , allowing end users to verify their accounts in seconds, using micro-deposits sent over RTP or FedNow rails. Instant Micro-Deposits can be used as a faster alternative to Same-Day Micro-Deposits at supported institutions.
    
    For Assets:
    
*   Deprecated `report_type` field used in [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) , and replaced it with `verification_report_type`. This change was made to avoid confusion with the existing `report_type` field used to by the `PRODUCT_READY` webhook to distinguish between Fast Asset Reports and Full Asset Reports.
    

For Signal:

*   Launched the Signal Dashboard to help customers monitor return rates and tune Signal risk score thresholds.

For Transactions:

*   Made [Personal Finance Categories](https://plaid.com/docs/transactions/pfc-migration/index.html.md) returned by default for all users. Personal Finance Categories are Plaid's newest and most accurate way of categorizing transactions, using more intuitive categories that correspond better to personal finance management use cases.

For Transfer:

*   Launched Transfer from beta to Early Availability (EA) status.
*   Added support for FedNow payments, which can be accessed by specifying `rtp` as the payment network.
*   Added Plaid Ledger. Your Plaid Ledger allows you to maintain a funds balance with Plaid, which can be used to fund payouts over FedNow and RTP rails. You can use APIs to move money in and our of your Ledger.
*   Removed Payment Profiles; access tokens are now the only supported mechanisms for connecting accounts on Transfer.
*   Removed `beacon_id`, as it was used only to support Guarantee. Guarantee is no longer offered and will be replaced by a more sophisticated set of risk management tools within Transfer.

For Income:

*   Updated API docs to reflect `"NOT LISTED"` as a potential value for `marital_status`.

For Statements (beta):

*   Released [Statements](https://plaid.com/docs/statements/index.html.md) in beta. Statements allows you to retrieve an exact PDF copy of a customer's statement at supported institutions.

##### August 2023 

For Enrich:

*   Added `frequency` field to recurring transactions to indicate the recurrence frequency.

For Identity Verification:

*   Added `area_code` match status to the responses of the [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) and [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) endpoints.

For Income:

*   Added a number of new categories for Payroll Income `canonical_description` field: `ALLOWANCE`, `BEREAVEMENT`, `HOLIDAY_PAY`, `JURY_DUTY`, `LEAVE`, `LONG_TERM_DISABILITY_PAY`, `MILITARY_PAY`, `PER_DIEM`, `REFERRAL_BONUS`, `REIMBURSEMENTS`, `RETENTION_BONUS`, `RETROACTIVE_PAY`, `SEVERANCE_PAY`, `SHIFT_DIFFERENTIAL`, `SHORT_TERM_DISABILITY_PAY`, `SICK_PAY`, `SIGNING_BONUS`, and `TIPS_INCOME`. Also made `null` a valid value.
*   Added `status` field to [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) to show the status of evaluated documents.
*   Added `payroll_income.parsing_config` to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to expose configuration options for risk signal evaluation.

For Liabilities:

*   Added `saving on a valuable education` (SAVE) as a student loan repayment plan type.

For Signal:

*   Added the ability to change an `initiated` status reported via [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) . Previously, attempting to change the status of a reported decision that was originally reported as `initiated` would result in an `INVALID_FIELD` error; now it is allowed.

For Transfer:

*   Added `failure_reason` to refund objects to indicate why a Transfer refund failed.

For Virtual Accounts:

*   Added `failure_reason` to [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) endpoints to indicate why a wallet transaction failed.

##### July 2023 

*   Added [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint to allow customers using processor partners to update the webhook endpoint associated with a processor token.

For Assets:

*   Made `asset_report_token` optional in [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) request to support future development of Asset Reports based on other types of tokens.

For Investments:

*   Added the `async_update` option for [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) , along with an accompanying `HISTORICAL_UPDATE` webhook. If `async_update` is enabled, the initial call to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) for an Item will be made as an async call with a webhook, similar to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) .

For Enrich:

*   Added `confidence_level` to `counterparty` and `personal_finance_category` fields.

For Identity Verification:

*   Added `date_of_birth` and `address` fields to `documentary_verification.documents[].extracted_data` in the response of all Identity Verification endpoints.
*   Mark all `region` and `postal_code` fields as nullable, to better support countries that do not use these fields.

For Transfer:

*   Added `transfer_id` and `status` filters to [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) request.
*   Added `status` field to the sweep object.

##### June 2023 

*   Added the `required_if_supported_products` field to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When using multiple Plaid products, you can use this field to specify products that must be enabled when the user's institution and account type support them, while still allowing users to add Items if the institution or linked account doesn't support these products. If a product in this field cannot be enabled at a compatible institution (for example, because the user failed to grant the required OAuth permissions, generating an `ACCESS_NOT_GRANTED` error), the Item will not be created, and the user will be prompted to try again in the Link flow.
    
*   Changed the behavior of the `oauth` field on the institution object. Previously, `oauth` would be `true` only if _all_ Items at an institution used OAuth connections. Now, `oauth` is true if _any_ Items at an institution use OAuth connections.
    
*   Changed the behavior of the `account_selection_enabled` flag in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To improve conversion, at institutions that provide OAuth account selection flows, this flag will be overridden and treated as though it were always `true`. For other institutions, the flag behavior is unchanged.
    

For Auth:

*   Added the ability to customize Same-day Microdeposit flows via the new `reroute_to_credentials` option in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Using this field, you can detect whether a user is attempting to use Same-day Microdeposits to add an institution that is supported via a direct Plaid connection, and optionally either require or recommend that they use a direct connection instead.

For Enrich:

*   Added `income_source` enum to `counterparty_type` field.

For Identity Verification:

*   Added the ability to prefill user data when retrying a verification by providing a `user` object to [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) .
*   Added `client_user_id` field to [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . It is recommended to use this field instead of `user.client_user_id`, although both fields are supported.

For Income:

*   Added `num_bank_statements_uploaded` to `document_income_results` object in [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) .

For Signal:

*   Removed the maximum length constraint for `client_user_id` when calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) or [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) .

For Transfer:

*   Added the ability to specify a `test_clock_id` when calling [/sandbox/transfer/sweep/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersweepsimulate) or [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) . If provided, the simulated action will take place at the `virtual_time` of the given test clock.
*   Made the `virtual_time` field optional when calling [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) . If a time is not provided, the current time will be used.
*   Updated the `sweep_id` format to be either a UUID or an 8-character hexadecimal string.
*   Made `next_origination_date` nullable in the recurring transfer object.

For Virtual Accounts:

*   Added address and date of birth to [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) .
*   Added payment scheme (`scheme`) to [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) .

##### May 2023 

For Assets:

*   Added support for `ASSETS: PRODUCT_READY` and `ASSETS: ERROR` webhooks to [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook)

For Identity:

*   Added `is_business_name_detected` to the [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) endpoint

For Identity Verification:

*   Added the `selfie_check` field to the Income Verification object, to report the status of a selfie check.

For Document Income:

*   Added the `INCOME_VERIFICATION_RISK_SIGNALS` webhook to indicate when [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) is ready to be called.

For Transfers:

*   Increased the maximum length of the `description` field in [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) to 15 characters.
*   Added the `/transfer/balance/get` endpoint.
*   To support prefunded credit processing, added the `credit_funds_source` field to distinguish between credits based on sweeps, RTP credit balances, and ACH credit balances, and made the `funding_account_id` field nullable.

For Processor partners:

*   Added [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) and [/processor/token/permissions/get](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsget) endpoints.
*   Added [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) endpoint to allow Processor partners to support the new beta Identity Match feature.

For Signal:

*   Added a `warnings` object to the [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) response.

##### April 2023 

For Income:

*   Added `STARTED` and `INTERNAL_ERROR` statuses to [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) .

For Document Income:

*   Released the [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) endpoint. This endpoint can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering.

For Identity Verification:

*   Documented several fields in the `user` object of [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as being officially supported methods of pre-filling user data in Link for the Identity Verification flow, as an alternative to [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . (While this worked in the past, it was not previously an officially supported or documented flow.) As part of this change, un-deprecated the `user.date_of_birth` field.

For Enrich:

*   Added `recurrence` and `is_recurring` fields to [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) .

##### March 2023 

*   To maximize conversion, updated Link to use a pop-up window for OAuth authentication rather than redirects on non-webview mobile web flows.
*   Clarified that `continue(from:)` is no longer required for iOS OAuth integrations using Plaid's iOS and React Native iOS SDKs.
*   Updated error codes for most `RATE_LIMIT` errors to be specific to the endpoint for which they apply.

For Auth:

*   Changed the Link UI for Instant Match and Automated Micro-deposits flows to increase conversion by reducing the number of screens in the flow and removing unnecessary input fields. No developer action is required as a result of this change.

For Transactions:

*   Added `ANNUALLY` as a possible frequency for recurring transactions in [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) .

For Identity:

*   Added [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) (beta) to simplify the process of using Identity for account ownership verification. [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) allows you to send user information such as name, address, email, and phone number, and returns a match score indicating how closely that data matches information on file with the financial institution, so that you no longer have to implement similarity matching logic on your own. [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) is currently in closed beta; to request access, contact your Account Manager or [contact Sales](https://www.plaid.com/contact) .

For Identity Verification:

*   Added [risk\_check object](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) to [Identity Verification API responses](https://plaid.com/docs/api/products/identity-verification/index.html.md) to provide more detail about the factors that influenced the risk check result.

For Assets:

*   Released Fast Assets functionality to General Availability (GA). With Fast Assets, you can create a Fast Asset Report with partial information (current balance and identity data) in about half the time as a Full Asset Report, then request the Full Asset Report later. Fast Assets is available free of charge to all Assets customers. For more information, see the [Assets API reference](https://plaid.com/docs/api/products/assets/index.html.md#asset_report-create-request-options-add-ons) .
*   Added the optional `days_to_include` field to [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) requests. This field allows you to optionally reduce the number of days displayed in an Asset Report, to improve usability for human reviewers.
*   Added Freddie Mac as an audit copy token partner with `auditor_id: freddie_mac`.
*   Added `credit_category` (beta) to transactions data returned by Asset Reports with Insights, describing the category of the transaction. Access to this field is in closed beta; to request access, contact your Account Manager.

For Income:

*   Added support for `bank_employment_results` data to [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) . Employment functionality is currently in closed beta; for more details, contact your Account Manager.

For Signal:

*   Added `warnings` field to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response.

For Virtual Accounts:

*   Added `transaction_id` to the Payment Initiation `PAYMENT_STATUS_UPDATE` webhook. This field will be present only when a payment was initiated using Virtual Accounts.
*   Added `payment_id` and `wallet_id` to the `WALLET_TRANSACTION_STATUS_UPDATE` webhook.

##### February 2023 

*   Added the `persistent_account_id` field (beta) to the `account` object. The `persistent_account_id` field identifies an account across multiple instances of the same Item, for use with Chase Items only, to simplify the management of Chase [duplicate Item behavior](https://plaid.com/docs/link/oauth/index.html.md#chase) . Access to this field is currently in closed beta; for more details, contact your Account Manager.

For Assets:

*   Beginning March 31, 2023, Assets will be updated to return `investment`, instead of `brokerage`, as the account type for investment accounts. `brokerage` may still be returned as an account sub-type under the `investment` account type.

For Income:

*   Added `employment` value to the `products` array for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Employment functionality is currently in closed beta; for more details, contact your account manager.

For Identity Verification:

*   Added `redacted_at` field in Identity Verification response and Documentary Verification Document component.

For Transfer:

*   Added the ability to specify a payment `network` (either `ach` or `same-day-ach`) when calling [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) .

For reseller partners:

*   Added `income_verification` and `employment` as supported products for [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) . Employment functionality is currently in closed beta.
*   Added the ability to specify `redirect_uris` to [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) .

For Virtual Accounts:

*   Increased the minimum length of the `reference` field for [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) to 6 characters.
*   To improve usability, added `wallet_id` field to [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) responses and to the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook.

For Payment Initiation:

*   Increased the minimum length of the `reference` field for [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) to 6 characters.
*   To improve usability, added `transaction_id` field to the [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhook. This field will be populated when the payment status is `PAYMENT_STATUS_SETTLED`.
*   Removed the deprecated `options.wallet_id` field from [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) and [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) .

For Signal:

*   Added `signal` to the products array. For most current Signal customers, Signal is automatically enabled for all of their Items; over time, Signal will be moving to a model similar to Plaid's other products, in which customers instead initialize an Item with signal by adding `signal` to the products array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

##### January 2023 

*   Released Plaid [React Native SDK 9.0.0](https://github.com/plaid/react-native-plaid-link-sdk) and Plaid [iOS SDK 4.1.0](https://github.com/plaid/plaid-link-ios) . All iOS integrations must upgrade to these SDKs by June 30, 2023 in order to maintain support for Chase OAuth flows on iOS. Any integrations using webviews will also be required to update their webview handlers by June 30, 2023. For more details on required webview updates, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#extending-webview-instances-to-support-certain-institutions) .
*   Released improvements to the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) : removing the requirement to provide a verified time for phone numbers and email addresses, making RUX flows available for more products, and adding Institution Boosting, which automatically surfaces institutions a user has previously linked to Plaid in the Link flow. Enabling the returning user experience can increase conversion by 8% or more. For more details, see [Returning user experience documentation](https://plaid.com/docs/link/returning-user/index.html.md) .

For Auth:

*   Updated [Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) to make a single one-cent micro-deposit, which will not be reversed, rather than multiple micro-deposits. This change will reduce costs and decrease the incentive for micro-deposit fraud. No changes are required on the part of developers to support this change. This change will automatically be rolled out to customers over the next several months.

For Transfer:

*   Added `expected_settlement_date` field to the Transfer object.
*   Added `funding_account_id` field to clarify which account is used to fund a transfer. This field replaces the older `origination_account_id`.

For Virtual Accounts:

*   Added `status` field to Wallet schema.

For Partners:

*   Added [PARTNER\_END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED](https://plaid.com/docs/api/partner/index.html.md#partner_end_customer_oauth_status_updated) webhook.

##### December 2022 

For Auth:

*   Announced upcoming [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) automatic enrollment to existing customers who have not yet been enabled for Instant Match by default. Instant Match is a higher-converting experience for Link that expands Auth coverage to more end users. All customers will be enabled for Instant Match by default unless they opt-out by January 19, 2023, which they can do by contacting their Account Manager.

For Assets:

*   Released relay tokens to beta, along with associated endpoints [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) , [/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) , [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) , and [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) . Relay tokens support sharing of Asset Reports with customers' authorized service providers, such as underwriters.

For Income:

*   For [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) , deprecated `amount`, `iso_currency_code`, and `unofficial_currency_code` at top levels in response in favor of new `total_amounts` field. This change enables more accurate reporting of income for users with income in multiple different currencies.
*   Added new possible values to `rate_of_pay` field returned by [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) : `WEEKLY`, `BI_WEEKLY`, `MONTHLY`, `SEMI_MONTHLY`, `DAILY`, and `COMMISSION`.
*   Added new `pay_basis` field to the response of [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) .

For Virtual Accounts:

*   Added `FUNDS_SWEEP` as a possible transaction type.

For Transfer:

*   Added [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) endpoint to provide information about which Items support Real Time Payments (RTP)
*   Added endpoints [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) , [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) , [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) , and [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) to support marketplaces and reseller partners in creating and managing transfer originators.
*   Added the ability to create and manage [recurring transfers](https://plaid.com/docs/transfer/recurring-transfers/index.html.md) . API changes include the new endpoints `/transfer_recurring/create`, [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) , [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) , and [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) , as well as the new webhooks `RECURRING_NEW_TRANSFER`, `RECURRING_TRANSFER_SKIPPED`, and `RECURRING_CANCELLED`, and the test endpoints [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) , [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) , [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) , and [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) .

For Enrich:

*   Released Enrich to Early Availability. Enrich access is now available by default in Sandbox. For details on requesting access to use Enrich with real data, see the [Enrich documentation](https://plaid.com/docs/enrich/index.html.md) .
*   Added support for legacy categories, using categories from [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) , in addition to the newer `personal_finance_category` schema.
*   Renamed counterparty type `delivery_marketplace` to `marketplace` and added counterparty type `payment_terminal`.

For the Reseller Partner API:

*   Added [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) endpoint to provide OAuth-institution registration information to Reseller Partners.

##### November 2022 

*   Released [Signal](https://plaid.com/docs/signal/index.html.md) to general availability. Signal uses machine learning techniques to evaluate a proposed ACH transaction and determine the likelihood that the transaction will be reversed. It also provides fields and insights that you can incorporate into your own data models. By using the Signal API, you can release funds earlier to optimize your user experience while managing the risk of ACH returns.

For Auth:

*   Enabled [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) by default for most existing customers.

For Investments:

*   Notified customers that customers must hold a CGS (CUSIP Global Services) license to obtain CUSIP and ISIN data. Beginning in mid-September 2023, customers who do not have a record of this license with Plaid will receive `null` data in these fields. To maintain access to these fields, contact your Plaid Account Manager or [investments-vendors@plaid.com](https://plaid.commailto:investments-vendors@plaid.com) .

For Payment Initiation:

*   Added the ability to initiate partial refunds by specifying an `amount` when calling [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) . As part of this change, added `amount_refunded` field to [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) .
*   Added support for local payment schemes for all supported currencies (previously, only EUR and GBP local payment schemes been supported), and added the enum values `LOCAL_DEFAULT` and `LOCAL_INSTANT` to represent them. In the UK, the `FASTER_PAYMENTS` enum value has been replaced by `LOCAL_DEFAULT`.
*   Removed support for currencies CHF and CZK.

For Virtual Accounts:

*   For improved consistency, renamed `/wallet/transactions/list` to [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) .
*   For clarity, renamed `start_date` to `start_time` in the [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) response to reflect that the field is a date-time.

For Transfer:

*   Made `account_id` nullable in the responses for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) and [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) .
*   Added `deleted_at` field to /payment\_profile/get response.
*   Added `refunds` field to the transfer object.
*   Added `refund_id` to the transfer event object.

For Reseller Partners:

*   Added the [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) endpoint to disable customers who have not yet been enabled in Production.

##### October 2022 

*   Added support for additional Link display languages: Danish, German, Estonian, Italian, Latvian, Lithuanian, Norwegian, Polish, Romanian, and Swedish.
*   Added support for additional countries: Denmark, Estonia, Latvia, Lithuania, Poland, Norway, and Sweden.
*   Added support for `USER_INPUT_TIMEOUT` as a value for `force_error` in the [Sandbox custom user](https://plaid.com/docs/sandbox/user-custom/index.html.md) schema.

For Auth:

*   Enabled [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) by default for all new customers.

For Investments:

*   Added `non-custodial wallet` to account subtypes.
*   Added `trade` investment transaction subtype as a subtype of `transfer` investment transaction type

For Income:

*   To improve reliability and developer ease of use, modified the multi-Item Link flow for Bank Income to use the new [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) endpoint rather than relying on Link events.
*   Added Bank Income status `USER_REPORTED_NO_INCOME`.
*   Added Income support to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) .
*   Deprecated `VERIFICATION_STATUS_PENDING_APPROVAL`.
*   Established a 128 character limit for the `client_user_id` field in the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) request.
*   Added `institution_name` and `institution_id` fields to [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) response.

For Virtual Accounts:

*   Added `options.start_time` and `options.end_time` to [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) request.
*   Added `last_status_update` and `payment_id` field to wallet transactions.

For Payment Initiation:

*   Added `transaction_id` field to the payment object.

For Transfer (beta):

*   Added support for RTP networks
*   Added decision rationale code `PAYMENT_PROFILE_LOGIN_REQUIRED` and the ability to update a Payment Profile via update mode. Also added /sandbox/payment\_profile/reset\_login to test this new update mode flow in Sandbox.
*   To improve consistency, renamed `LOGIN_REQUIRED` decision rationale to `ITEM_LOGIN_REQUIRED`.
*   Deprecated `origination_account_id` from [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) endpoint.
*   Added new `originator_client_id` field to support Third-Party Senders (TPS).

For Wallet Onboard (beta):

*   Released Wallet Onboard to beta.

For Partner Resellers:

*   Added [Partner reseller endpoints](https://plaid.com/docs/api/partner/index.html.md) to improve the experience of onboarding new customers for delegated diligence partners.

##### September 2022 

*   Added the ability to simulate the `USER_INPUT_TIMEOUT` error in [Sandbox](https://plaid.com/docs/sandbox/test-credentials/index.html.md#error-testing-credentials) .
*   Added the ability to specify account mask when using [custom Sandbox users](https://plaid.com/docs/sandbox/user-custom/index.html.md) .

For Investments:

*   Added support for crypto wallet investment account subtype `non-custodial wallet` and crypto `trade` investment transaction type.
*   Made `institution_price_as_of` nullable.

For Transfer (beta):

*   Added support for client-side beacons. A beacon is now required when using Guarantee with web checkout flows.
*   Removed the `idempotency_key` from the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) response.
*   Added `settled` and `swept_settled` transfer events and event statuses.
*   Added `standard_return_window` and `unauthorized_return_window` fields to the Transfer object.

For Payment Initiation:

*   Added `AUTHORISING` wallet status.
*   Added `recipient_id` to the [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) , [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) , and [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) responses.

For Assets:

*   Added `days_to_include` and `options` to [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) request.

##### August 2022 

*   Released [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) and [Monitor](https://plaid.com/docs/monitor/index.html.md) to General Availability (GA).
    
*   Added `issuing_region` as a field in the extracted data for Identity Verification documents
    
*   Extended support for Android Link SDK versions prior to 3.5.0, iOS Link SDK versions prior to 2.2.2, and Link React Native SDK versions prior to 7.1.1. Previously, these SDK versions had been scheduled to be sunset on November 1, 2022. The sunset has been canceled and Plaid will now continue to support these versions past November 2022. We still recommend you use the latest SDK versions.
    

For Payment Initiation:

*   Added support for [virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) .
*   Added support for additional currencies PLN, SEK, DKK, NOK, CHF, and CZK.
*   Added `PAYMENT_STATUS_SETTLED` payment status.

For Income:

*   Removed verification fields from [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and /income/verification/paystubs/get
*   Removed `pull_id` field from [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget)
*   Added payroll institution to /credit/income/precheck

##### July 2022 

For [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `user` object:

*   Deprecated the unused fields `ssn`, `date_of_birth`, and `legal_name`.
*   Added the `name`, `address`, and `id_number` parameters to support Identity Verification.

For Payment Initiation:

*   Added `bin` as a field under `institution_metadata` for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

For Income:

*   Add `stated_income_sources` as a field under `income_verification` for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   Add 1099 data to [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) response.
*   Deprecate `paystubs.verification` in [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) response.

For Transfer:

*   Add `payment_profile_id` to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and make `account_number` and `access_token` optional for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) and [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . These changes will support forthcoming Transfer functionality.
*   Add `user_present` a required field for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) when using Guarantee (beta)
*   Deprecated the no-longer-used `swept` and `reverse_swept` statuses.

##### June 2022 

For Auth:

*   Launched [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) (formerly known in beta as Flexible Auth or Flex Auth) to all customers. Auth Type Select allows you to optionally route end users directly to micro-deposit-based verification, even if they are eligible for Instant Match or Instant Auth.

For Transfer:

*   Made Plaid Guarantee available in beta. Guarantee allows you to guarantee the settlement of an ACH transaction, protecting you against fraud and clawbacks.
*   Added `TRANSFER_LIMIT_REACHED` to Transfer authorization decision rationale codes.

For Income:

*   Added the `accounts` object with `rate_of_pay` data to the response for [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) .

For Payment Initiation (UK and Europe only):

*   Launched payment consents, which can be used to initiate payments on behalf of the user.

##### May 2022 

*   Added [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) and [Monitor](https://plaid.com/docs/monitor/index.html.md) products in Early Access. Identity Verification checks the identity of users against identity databases and user-submitted ID documents, while Monitor checks user identities against government watchlists.

For Transactions:

*   Added [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , which improves ease of use for handling transactions updates. While [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) continues to be supported and there are no plans to discontinue it, all new and existing integrations are encouraged to use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) instead of the older [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint.

For Income:

*   Added `employee_type` and `last_paystub_date` to [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) response.
*   Removed `uploaded`, `created` and `APPROVAL_STATUS_APPROVED` enum strings, as these are no longer used.

##### April 2022 

*   Added the ability to default Link to highlighting a specific institution when launching Link, via the [institution\_data](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-institution-data) request field.
    
*   Launched [Income](https://plaid.com/docs/income/index.html.md) to general availability. Income allows you to verify the income of end users for purposes of loan underwriting. Various updates were also made to Income interfaces prior to launch; Income beta customers have been contacted by their account managers with details on the differences between the beta API and the released API.
    

For Transactions:

*   Added [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) , which provides information about recurring transaction streams that can be used to help your users better manage cash flow, reduce spending, and stay on track with bill payments. This endpoint is not included by default as part of Transactions; to request access to this endpoint and learn more about pricing, contact your Plaid account manager.

For Auth:

*   Added Highnote as a processor partner. For a full list of all Auth processor partners, see [Auth Payment Partners](https://plaid.com/docs/auth/partnerships/index.html.md) .

##### March 2022 

*   Introduced the Institution Select shortcut, which enables you to highlight a matching institution on the Institution Select pane.
*   Added `institution_data` request field to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint, which accepts `routing_number`.
*   Added `match_reason` to metadata field for `MATCHED_SELECT_INSTITUTION`, which indicates whether `routing_number` or `returning_user` resulted in a matched institution.
*   Added support for `AUTH_UPDATE` and `DEFAULT_UPDATE` webhooks to [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) . Also added `webhook_type` parameter to this endpoint to support different `DEFAULT_UPDATE` webhooks for Transactions, Liabilities, and Investments.

For Income:

*   New set of API endpoints added and numerous updates made for General Availability release. Existing beta endpoints are still supported but marked as deprecated. For more details, see the [Income docs](https://plaid.com/docs/income/index.html.md) and [Income API reference](https://plaid.com/docs/api/products/income/index.html.md) .

For Auth:

*   Added Apex Clearing, Checkout.com, Marqeta, and Solid as processor partners.

For Payment Initiation:

*   Added support for the `IT` country code.
*   Added support for searching by `consent_id` to [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) .

For Bank Transfer (beta):

*   Added `wire_routing_number` parameter to [/bank\_transfer/migrate\_account](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfermigrate_account) .

For Transfer (beta):

*   Removed `permitted` decision for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) .
*   Added [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) endpoint.

##### February 2022 

*   For Transactions, released new personal finance categories to provide more intuitive and usable transaction categorization. Personal finance categories can now be accessed by calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) with the `include_personal_finance_category` option enabled.
*   For Income, removed several unused fields and endpoints, including removing `income_verification_id` from [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) and removing the /income/verification/summary/get and /income/verification/paystub/get endpoints.

For Transfer (beta):

*   Deprecated the `idempotency_key` parameter, as idempotency is now tracked via other identifiers.
*   Made `repayment_id` a required parameter for /transfer/repayment/return/list.
*   Made guaranteed fields required in Transfer endpoints.

##### January 2022 

*   Added the ability to test the `NEW_ACCOUNTS_AVAILABLE` webhook via [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) .
*   Updated [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) to accept empty or `null` webhook URLs.
*   Updated institutions endpoints to accept null values as input for optional input fields.

For Transfer (beta):

*   Added publicly documented sweep endpoints to provide visibility into the status of Transfer sweeps.
*   Added `iso_currency_code` throughout the API to future-proof for multi-currency support (currently only USD is supported).
*   Made `repayment_id` required in /transfer/repayment/return/list endpoint

For Bank Transfer (beta):

*   Removed `receiver_pending` and `receiver_posted` from bank transfer event types, and removed receiver details from events.

For Payment Initiation:

*   Added payment scheme support for EU payments.
*   Removed `scheme_automatic_downgrade` from [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) .
*   Updated webhooks to use new statuses.

For Income:

*   Added `DOCUMENT_TYPE_NONE` value for document type.
*   Made employer address fields no longer required in /income/verification/precheck.

##### December 2021 

*   For Transfer, updated the schema definitions for [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) and [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) .
*   For Income, deprecated the status `VERIFICATION_STATUS_DOCUMENT_REJECTED`.
*   For Payment Initiation, added several new statuses, including `PAYMENT_STATUS_REJECTED`.

##### November 2021 

*   For Payment Initiation, added the new status `PAYMENT_STATUS_EXECUTED` and renamed `emi_account_id` to `wallet_id`.
*   For [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) , added the fields `merchant_name` and `check_number` to the Transactions schema, to match the Transactions schema already being used by the Transactions API.
*   For Income, added the new status `VERIFICATION_STATUS_PENDING_APPROVAL`.

##### October 2021 

Multiple changes to the Income API:

*   Added the ability to verify submitted paystubs against a user's transaction history by adding the `income_verification.access_tokens` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and updating /income/verification/paystubs/get to return the income verification status for each paystub.
*   Added a `precheck_id` field to /income/verification/create and an `income_verification.precheck_id` field to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to fully support use of the /income/verification/precheck endpoint to check whether a given user is supportable by the Income product.
*   Extensive changes to the paystub schema returned by /income/verification/paystubs/get, including adding new fields and deprecating old ones. For details, contact your Plaid Account Manager.
*   Officially deprecated the `income_verification_id` in favor of the Link token-based income verification flow.
*   Added an `item_id` field to the [income\_verification webhook](https://plaid.com/docs/api/products/income/index.html.md#income_verification) and corresponding [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) endpoint.
*   Added `employer.url` and `employer.address` fields to the /income/verification/precheck endpoint.
*   Added a `doc_id` field to /income/verification/taxforms/get.

Other changes:

*   For institutions endpoints, marked the `status` enum as deprecated in favor of the more detailed `breakdown` object.
*   Added `DE` as a supported country to support Payment Initiation use cases.

##### September 2021 

*   Released Account Select v2, including the new [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhook, for improved end-user sharing controls. All implementations must migrate to Account Select v2 by March 2022.
*   Added the ability to check which types of [Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) an institution supports via a new `auth_metadata` object now available from [Institutions endpoints](https://plaid.com/docs/api/institutions/index.html.md)
*   Added the /income/verification/precheck endpoint to check whether a given user is supportable by the Income product.
*   Added `initiated_refunds` field to [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) to show refunds associated with payments.
*   Added fields `include_personal_finance_category_beta` and `personal_finance_category_beta` to Transactions endpoints as part of a beta for new Transactions categorizations. To request beta access, contact [transactions-feedback@plaid.com](https://plaid.commailto:transactions-feedback@plaid.com)
*   Removed some fields (`direction`, `custom_tag`, `iso_currency_code`, `receiver_details`) and receiver event types from [Bank Transfer (beta) endpoints](https://plaid.com/docs/api/products/transfer/index.html.md) and made `ach_class` a required field.
*   Added support for the currency type Bitcoin SV.

##### August 2021 

*   Released [UX improvements to Link](https://plaid.com/blog/enhancements-to-link-for-an-improved-user-experience/) .
*   Launched [Plaid OpenAPI schema](https://github.com/plaid/plaid-openapi) and new, [auto-generated client libraries](https://plaid.com/blog/open-api-client-libraries/) for Python, Node, Java, Ruby, and Go to General Availability.
*   Added the ability to use [custom Sandbox data](https://plaid.com/docs/sandbox/user-custom/index.html.md) with the Investments product.
*   For [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , added the `check_number` field.
*   Updated the list of [ACH partners](https://plaid.com/docs/auth/partnerships/index.html.md) , adding Treasury Prime.
*   For [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) , added `min_last_updated_datetime` option to request.
*   Multiple schema and endpoint updates for the [Bank Transfers (beta)](https://plaid.com/docs/bank-transfers/index.html.md) and [Income (beta)](https://plaid.com/docs/income/index.html.md) products. Beta participants can receive details on updates from their account managers.

##### July 2021 

*   Added new webhook for Deposit Switch.
*   Added optional `country_code` and `options` parameters to deposit switch creation endpoints, as well as new values for the `state` enum in the response.
*   For Deposit Switch, added additional response fields `employer_name`, `employer_id`, `institution_name`, `institution_id`, and `switch_method`.
*   Updated the list of [ACH partners](https://plaid.com/docs/auth/partnerships/index.html.md) , including adding Alpaca, Astra, and Moov.
*   For [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , added the fields `include_original_description` and `original_description` in the request and response, respectively.

##### June 2021 

*   Chase now supports real-time payments and same-day ACH for OAuth-based connections.
*   Added new Investment account subtypes `life insurance`, `other annuity`, and `other insurance`.
*   Added new error codes [INSTITUTION\_NOT\_ENABLED\_IN\_ENVIRONMENT](https://plaid.com/docs/errors/institution/index.html.md#institution_not_enabled_in_environment) , [INSTITUTION\_NOT\_FOUND](https://plaid.com/docs/errors/institution/index.html.md#institution_not_found) , and [PRODUCT\_NOT\_ENABLED](https://plaid.com/docs/errors/item/index.html.md#product_not_enabled) . These codes replace more generic errors that could appear when working with OAuth institutions or API-based institution connections.
*   Began rolling out improvements to reduce balance latency.
*   Released a new representation of cryptocurrency, to represent crypto holdings more similarly to investments, rather than foreign currency, in order to match how most popular institutions represent crypto. `institution_price` will now reflect the USD price of the currency, as reported by the institution, and `institution_value` will reflect the value of the holding in USD. `close_price` and `close_price_as_of` will now be populated. `iso_currency_code` will be set to `USD` and `unofficial_currency_code` will be set to `null`.

##### May 2021 

*   Improved the UI for [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) and enabled it for all "Pay as you go" customers. Customers with a monthly contract who would like to use Instant Match should contact their Plaid Account Manager.
*   Removed the requirement to be enabled by Support in order to request an [Asset Report with Insights](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) .
*   For the Payment Initiation product, launched [Modular Link](https://plaid.com/blog/improving-the-payments-experience) , allowing further UI customization.
*   For the Payment Initiation product, added an `options` object to [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) to support restricting payments originating from specific accounts.
*   For the Liabilities product, added a [DEFAULT\_UPDATE webhook](https://plaid.com/docs/api/products/liabilities/index.html.md#default_update) to indicate changes to liabilities accounts.
*   Made [Item Debugger and improved Institution Status](https://plaid.com/blog/item-debugger-institution-status/) available to 100% of developers.
*   Added Link [Consent pane customization](https://plaid.com/docs/link/customization/index.html.md#consent-pane-customizations) .
*   Added the ability to use wildcards to specify a subdomain in an OAuth redirect URI.
*   Clarified that the following Link onEvent callbacks are stable: `OPEN`, `EXIT`, `HANDOFF`, `SELECT_INSTITUTION`, `ERROR`, but the remaining are informational.

##### April 2021 

*   In order to support the beta generated client libraries, added the ability to provide `client_id` and `secret` [via headers](https://plaid.com/docs/api/index.html.md#api-protocols-and-headers) instead of as request parameters.
*   Added the `min_last_updated_datetime` parameter to [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) to handle institutions that do not always provide real-time balances, and added the corresponding `LAST_UPDATED_DATETIME_OUT_OF_RANGE` error.
*   Removed `last_statement_balance` from the official documentation for [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) , as it was not ever returned.
*   Fixed the case of submitting an invalid client ID to return an [INVALID\_API\_KEYS](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_api_keys) error instead of an `INTERNAL_SERVER_ERROR`, in order to match documented behavior.

##### March 2021 

*   Launched [Plaid Income (beta)](https://plaid.com/income/) for verifying income and employment.
*   Added the ability to specify an `end_date` for standing orders in the [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md#standing-orders-uk) product.
*   Updated list of active processor partners.
*   Added [webhook](https://plaid.com/docs/bank-transfers/webhook-events/index.html.md) to notify of new Bank Transfers events.
*   Added [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) endpoint to test Bank Transfers webhooks.
*   Added `auth_flow` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to support Flexible Auth (beta).
*   Updated the [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) endpoint to accept `address.country_code` (preferred) instead of `address.country` (accepted, but deprecated).
*   Removed the `MATCHED_INSTITUTION_SELECT` transition view event, after consolidating the returning user institution select view.
*   Added the [SELECT\_BRAND](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-BRAND) onEvent callback, after shipping a change that groups institution login portals within the same institution brand.
*   Stopped sending `IS_MATCHED_USER` and `IS_MATCHED_USER_UI` because these events are duplicates. You should use `MATCHED_CONSENT` and `MATCHED_SELECT_INSTITUTION` to identify when a returning user is recognized and chooses an institution that we pre-matched.

##### February 2021 

*   Added additional [payment error codes](https://plaid.com/docs/errors/payment/index.html.md) .
*   Added the UK-only fields [authorized\_datetime](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-transactions-authorized-datetime) and [datetime](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-transactions-datetime) fields to the `transaction` object, for more detailed information on when the transaction occurred.
*   Added `update_type` field to the `item` object. This field will be used to support upcoming connectivity improvements to accounts with multi-factor authentication.
*   Added optional `ssn` and `date_of_birth` fields to the `user` object in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to support upcoming functionality enhancements.
*   Released an [OpenAPI file](https://github.com/plaid/plaid-openapi) describing the Plaid API.

##### January 2021 

*   Launched Deposit Switch (beta) for transferring direct deposits from one account to another.
*   Improved error handling to treat some invalid input errors that were previously treated as 500 errors as `INVALID_INPUT` errors instead.

##### December 2020 

*   Made Bank Transfers (beta) available for testing in the Development environment.
*   Added `investments_updates` to the `status` object returned by Institutions endpoints.

##### November 2020 

*   Removed some internal-only, pre-beta products from appearing in the [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) response.
*   Restored the `/item/public_token/create` and `/payment_initiation/payment/token/create` endpoints to API version 2020-09-14 to avoid disrupting update mode for end users on older mobile SDKs that do not support Link tokens. These endpoints are still deprecated, and it is recommended you update mobile apps to the latest SDKs as soon as possible.

##### October 2020 

*   Released API version 2020-09-14. See the [version changelog](https://plaid.com/docs/api/versioning/index.html.md#version-2020-09-14) for details.
*   Added support for mortgages to [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) .
*   Released [Bank Transfers](https://plaid.com/docs/bank-transfers/index.html.md) to closed beta.
*   To improve consistency with other error types, changed the error type for Bank Transfers errors from `BANK_TRANSFER` to `BANK_TRANSFER_ERROR`.
*   Added the fields `user.phone_number`, `user_email.address`, `user.phone_number_verified_time` and `user.email_address_verified_time` to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to support the new [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) , which allows users a more seamless Link flow.

##### August 2020 

*   Introduced [standing orders](https://blog.plaid.com/recurring-payments-with-standing-orders/) to [Payment Initiation](https://plaid.com/uk/products/payment-initiation/) for our UK and Europe customers. If applicable, your users will now be able to make recurring scheduled payments with a single authorization.
*   Expanded access to [full Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) to more developers. If you would like to use micro-deposit based verification and don't have access to it, contact your Plaid Account Manager.
*   Updated Link error messages to provide more actionable instructions for end users, making resolution troubleshooting easier.
*   Made [account filtering](https://blog.plaid.com/improvements-to-plaid-link-with-account-filtering-and-updated-error-messaging/) available across all our products, so you can configure the Link flow to guide end users in selecting relevant institutions and accounts.

##### July 2020 

*   Added the [ITEM: USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) webhook, which will notify you when a user contacts Plaid directly to delete their data or change their data sharing preferences with your app.
    
*   Released Link tokens, the new preferred way to use Link, replacing the public key. To learn how to migrate your application to use Link tokens, see the [Link token migration guide](https://plaid.com/docs/link/link-token-migration-guide/index.html.md) .
    

##### June 2020 

*   Added a new `merchant_name` field to the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint for the US and Canada, providing clearer and more consistent merchant names for 95% of existing transactions.
*   Added the [PAYMENT\_INITIATION:PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhook, which pushes instant notifications when payment status changes for the [UK Payment Initiation product](https://plaid.com/uk/products/payment-initiation/) .
*   Added the ability to create payment recipients via sort codes and account numbers, not just IBANs.

##### May 2020 

*   We launched a new open finance platform called [Plaid Exchange](https://blog.plaid.com/introducing-plaid-exchange/) that enables financial institutions to build a consumer-permissioned data access strategy and strengthen the ability of end users to reliably access their financial data.

##### April 2020 

*   Launched [Payment Initiation](https://plaid.com/uk/products/payment-initiation/) in the UK, which offers an easy way for users to fund their accounts, make purchases, and pay invoices—all from their favorite apps or websites.

##### March 2020 

*   Added the ability to [filter by account\_subtype](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , allowing you to further optimize the Link flow.
*   Added the `HOLDINGS: DEFAULT_UPDATE` and `INVESTMENT_TRANSACTIONS: DEFAULT_UPDATE` webhooks, which will fire each time data has successfully refreshed for Holdings and Investments Transactions.

##### February 2020 

*   Added [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , which enables you to pull a user’s transactions on demand.
*   Added [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) , which allows you to verify the authenticity of incoming webhooks.

##### January 2020 

*   Added `store_number`, `authorized_date`, and `payment_channel` to the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) response.
*   Added the `investment_transactions.subtypes` field to provide more granular detail about the tax, performance, and fee impact of investments transactions.

##### November 2019 

*   Added the `status.investments.last_successful_update` and `status.investments.last_failed_update` fields to the data returned by [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) .
*   Launched official support for Link on React Native with a new [SDK](https://github.com/plaid/react-native-plaid-link-sdk) , bringing unified support to React Native apps.

##### October 2019 

*   Added the `status.item_logins.breakdown` data to [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) and the Developer Dashboard.
*   Added the `routing_numbers` field to the Institutions object. You can also filter institutions via the `options.routing_numbers` field in each Institutions API endpoint.

##### September 2019 

*   Added support for [credit card details](https://blog.plaid.com/liabilities-credit-cards) to the Liabilities product.
*   Added Canada-specific account subtypes, including RRSP, RESP, and TFSA, to the Investments product.

##### August 2019 

*   Among numerous other improvements to Liabilities, such as expanded data access, added a new `loan_type`: `cancelled` to the Liabilities product.

##### July 2019 

*   We launched [Liabilities](https://blog.plaid.com/liabilities/) , which enables developers to access a feed of standardized student loan details from the largest U.S. servicers including Navient, Nelnet, FedLoan, Great Lakes, and many more.

##### June 2019 

*   Launched [Investments](https://blog.plaid.com/investments/) , which allows developers, fintech apps, and financial institutions to create a holistic view of their customers’ investments.
*   Added the `status.transactions_updates` field, exposing Transactions health to both the [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint and the Dashboard.

##### May 2019 

*   We enhanced the [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) endpoint to now return [account-level identity information](https://plaid.com/docs/api/products/identity/index.html.md#identityget) within the `accounts` object where available.
*   We released [API version 2019.05.29](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) to enable European institution coverage and provide nomenclature and schema updates required by Identity and future products.

##### March 2019 

*   We updated the [institutions endpoints](https://plaid.com/docs/api/institutions/index.html.md) so you can now retrieve bank logos, colors, and website URLs to use to customize your in-app experience.
*   We enabled triggering and testing of webhooks on demand via the new [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) endpoint.

##### February 2019 

*   We launched [new features for Auth](https://blog.plaid.com/new-auth/) , enabling developers to authenticate accounts from any bank or credit union in the U.S. Link automatically guides end-users to the best way to authenticate their account based on the bank they select.

##### November 2018 

*   Added a new [Insights](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) feature, which provides cleaned and categorized transaction data in an Asset Report. In addition to transaction categories, lenders will be able to retrieve merchant names and locations for transactions to use in building risk models.
*   Improved the Link experience by informing users about connectivity issues with banks before connecting their account. When banks are experiencing significant issues, users will temporarily be directed to connect their account at a different bank to reduce frustration and drop-off during the onboarding process.

##### September 2018 

*   We added the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint, so you can create a new Asset Report with the latest account balances and transactions for a borrower, based on the old report.

##### August 2018 

*   We added [account filtering](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) , which gives you the ability to exclude unnecessary accounts from appearing in an Asset Report.

##### June 2018 

*   Added historical account balances to the PDF version of Asset Reports, bringing them closer in line with the core JSON endpoint.

##### May 2018 

*   We released the [2018-05-22 version](https://plaid.com/docs/api/versioning/index.html.md#version-2018-05-22) of the Plaid API.
*   We enabled distinct API secrets [to now be be set](https://blog.plaid.com/api-secrets/) for the Sandbox, Development, and Production environments.
*   Added the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint, which enables the creation of Items in the Sandbox environment directly via the API (without Link).

##### April 2018 

*   Officially launched the [Assets](https://plaid.com/products/assets/) product. Assets is approved by Fannie Mae for [Day 1 Certainty™](https://www.fanniemae.com/singlefamily/day-1-certainty) asset verification.

##### March 2018 

*   Rolled out several Assets features, including webhooks for Asset Report generation and full support for Audit Copy token generation and Fannie Mae’s Day 1 Certainty™ program, while improving existing features like pending transaction support in PDF reports.

##### February 2018 

*   Released Assets as a beta product.

---


# Consumer Report (by Plaid Check) - Implementation | Plaid Docs

Add Consumer Report to your app 
================================

#### Onboard your users to Plaid Check to generate cash flow insights 

This guide will walk you through onboarding your users to Plaid Check, so you can generate cash flow insights for your customers by creating a Consumer Report.

This is designed as a granular, step-by-step walkthrough showing one option for a simple Plaid Check integration for customers new to Plaid. Plaid also offers a [no-code integration option](https://plaid.com/docs/check/index.html.md#no-code-integration-with-the-credit-dashboard) and a [high-level integration overview](https://plaid.com/docs/check/index.html.md#standard-integration-flow) .

If you are migrating to Plaid Check Consumer Reports from a different Plaid product, see the corresponding migration guide: [Migrate from Assets](https://plaid.com/docs/check/migrate-from-assets/index.html.md) , [Migrate from Income](https://plaid.com/docs/check/migrate-from-income/index.html.md) , or [Migrate from Transactions](https://plaid.com/docs/check/migrate-from-transactions/index.html.md) .

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid Check API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed these client libraries, initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create a user token 

Your next step is to create a `user_token` that will represent the end user.

To create a `user_token`, make a call to the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. This endpoint requires a unique `client_user_id` value to represent the current user. Typically, this value is the same identifier you're using in your own application to represent the currently signed-in user.

In addition, you will need to pass in a `consumer_report_user_identity` object to use Plaid Check products for this user. In this field, you should pass in user identity data that has been provided by your user for consumer report purposes.

You can only create one `user_token` per `client_user_id`. If you try to create a `user_token` with a `client_user_id` that you have previously sent to this endpoint, you will receive an error.

The [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint will return a randomly generated string for both the `user_token` and the `user_id`. Make sure to save both values. You send the `user_token` to Plaid Check to generate reports, and Plaid Check will use the `user_id` to refer to this user when it sends you a webhook.

Depending on your application, you might wish to create this `user_token` as soon as your user creates an account, or wait until shortly before your application would want to generate a report for this user.

#### Create a Link token 

Link is a client side UI widget that provides a secure, elegant flow to guide your users through the process of connecting Plaid Check with their financial institutions.

Before initializing Link, you will need to create a `link_token`. A `link_token` is a short-lived, single-use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint from your server.

When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you'll include an object telling Plaid Check about your application as well as how to customize the Link experience. In addition to the required parameters, you will need to provide the following:

*   For `user_token`, provide the `user_token` you created in the previous step.
*   For `products`, pass in `cra_base_report`, plus any additional Plaid Check products you wish to use (`cra_income_insights`, `cra_partner_insights`, and/or `cra_network_insights`), along with any additional Plaid Inc. products you are using. Note that Plaid Check products can't be used in the same Link flow with Income or Assets.
*   Provide a `webhook` URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your report is ready.
*   Include the appropriate options for the products you are using in the `cra_options` object.
*   Include a `consumer_report_permissible_purpose` parameter specifying your purpose for generating an Consumer Report.
*   On mobile, specify the `redirect_uri` and/or `android_package_name` fields as necessary, per the relevant [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform.

Send the `link_token` you get back in the response to your client application.

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Using Plaid Check products alongside Plaid products 

If you wish to use Plaid Inc. products (Transactions, Auth, etc.) alongside Plaid Check products, you can. You can just add those products to the appropriate products array when sending a request to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Link will take the user through a hybrid flow, where we establish connections to both Plaid Check and Plaid Inc. at the same time. One exception is that you cannot use the Plaid Inc. Income or Assets in the same session as a Plaid Check product. Instead, you should use the similar CRA Income Insights or CRA Base Consumer Report products.

#### Initialize Link 

Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the appropriate section in the [Link documentation](https://plaid.com/docs/link/index.html.md) . To integrate with Embedded Link, visit these [integration steps](https://plaid.com/docs/link/embedded-institution-search/index.html.md#integration-steps) .

##### Install the Link library 

You will need to install the Link JavaScript library in order to use Link in your web application.

```jsx

  Extend my Credit
  

```

##### Configure the client-side Link handler 

To run Link, you'll first need to retrieve the `link_token` from the server as described above. Then call `Plaid.create()`, passing along that token alongside other callbacks you might want to define. This will return a handler that has an `open` method. Call that method to open up the Link UI and start the connection process.

```javascript
const linkHandler = Plaid.create({
  token: link_token_from_previous_step,
  onSuccess: (public_token, metadata) => {
    // Typically, you'd exchange the public_token for an access token.
    // You won't do that with Plaid Check products.
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid Check.
  },
});


linkHandler.open();
```

If you've used Link in the past with products created by Plaid, you're probably used to taking the `public_token` received from Link and exchanging it on your server for a persistent `access_token`. That is not necessary for products created by Plaid Check, and is only necessary if you are using the hybrid flow, where you are using Plaid Inc. products (Transactions, Auth, etc.) alongside Plaid Check products.

#### Generate a report 

If you have included the `consumer_report_permissible_purpose` flag in your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) configuration, Plaid Check will start generating the Consumer Report for your user once they have completed the Link process.

Consumer Reports expire 24 hours after they have been created. After that point, you can [generate a new report](https://plaid.com/docs/check/add-to-app/index.html.md#generating-updated-reports) by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , passing along the `user_token` you created earlier.

#### Listen for webhooks 

After a user has finished using Link, it may take some time before the Consumer Report is available for you to retrieve. Listen for the `CHECK_REPORT_READY` webhook to know when it is safe to request the appropriate set of product data.

```javascript
app.post('/server/receive_webhook', async (req, res, next) => {
  const product = req.body.webhook_type;
  const code = req.body.webhook_code;
  if (product === 'CHECK_REPORT') {
    if (code === 'CHECK_REPORT_READY') {
      const userId = req.body.user_id;
      // It is now okay to start fetching Consumer Report data for this user
      fetch_cra_report_for_user(userId);
    } else if (code === 'CHECK_REPORT_FAILED') {
      const userId = req.body.user_id;
      // Handle this error appropriately
      report_error_with_generating_report(userId);
    }
  }
  // Handle other types of webhooks
});
```

The `user_id` value included in this webhook is the same `user_id` that was returned from the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) call.

#### Request product data 

Once Plaid Check has informed you that your report is ready, you can use one of the Plaid Check product endpoints ([/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , or [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) ) to retrieve the appropriate cash flow insights. You can attempt to retrieve any type of product data, even if you didn't initialize it in the `products` array when you called [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . However, retrieving new products might incur some latency as Plaid Check generates the new insight data.

Reports expire 24 hours after they have been created (either through a Link session that included the `consumer_report_permissible_purpose` parameter or through a [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) call). If you don't fetch any product data on top of this report within that time frame, you will need to generate a new Consumer Report.

#### Handling multiple institutions 

If you would like your Consumer Report to include information from multiple institutions, the simplest way is to add the `enable_multi_item_link: true` flag to your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call to enable [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . Your user will then have the option to connect to as many institutions as they wish during their Link session, and the generated report will contain data from each institution that the user connects to.

##### Adding institutions after the initial Link session 

If your user wants to add additional institutions _after_ their initial Link session, you may do so by once again generating a Link token (using the same `user_token` as before, and including at least one Plaid Check product in the products array), and opening a new Link session on the client.

If you include a `consumer_report_permissible_purpose` flag in this new Link token, Plaid Check will start generating a new report for your user when they are done with this Link session. However, this report will _only_ contain data from the institution that the user connected to during this most recent Link session.

In the more likely scenario that you want to generate a full report that includes data from all institutions that the user has connected to, you should _not_ include a `consumer_report_permissible_purpose` flag in this new Link token. Instead, when the user is done, re-generate your Consumer Report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) as described in the [Generating updated reports](https://plaid.com/docs/check/add-to-app/index.html.md#generating-updated-reports) section below.

#### Testing in Sandbox 

Because Consumer Report information is heavily dependent on income data, Plaid recommends using the test accounts designed for producing realistic looking income data, such as `user_bank_income` (with the password `{}`). The basic Sandbox credentials (`user_good`/`pass_good`) do not return good income data.

Plaid also has additional test users to represent different levels of creditworthiness. For details, see [Credit and Income testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) .

When using special Sandbox test credentials (such as `user_bank_income` / `{}`), use a non-OAuth test institution, such as First Platypus Bank (ins\_109508) or many smaller community banks. Special test credentials may be ignored when using the Sandbox Link OAuth flow.

#### Generating updated reports 

If, after some time has passed, you wish to generate a new report with updated data (or a user has connected additional institutions), you can do so by performing the following steps:

1.  Generate the new report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) with the same `user_token` you used earlier.
2.  Wait for the `CHECK_REPORT_READY` webhook.
3.  Once you have received the webhook, use one of the Plaid Check product endpoints ([/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , or [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) ) to retrieve the corresponding product data.

---


# Consumer Report (by Plaid Check) - Introduction | Plaid Docs

Introduction to Consumer Report  
=================================

#### Use Consumer Report for smarter credit and lending decisions powered by Plaid Check 

Get started with Consumer Report

[API Reference](https://plaid.com/docs/api/products/check/index.html.md) [Request Access](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) [Demo](https://plaid.coastdemo.com/share/67ed96db47d17b02bdfc4a88?zoom=100)

#### Overview 

Evaluate a consumer’s income, assets, employment, and financial stability in seconds based on insights and attributes derived from cash flow data. Get comprehensive, up-to-date bank account data to grow qualified borrowers, manage risk, and make credit and verification decisions with confidence - all through a single, high-converting UX.

To see a full financial picture, Consumer Report, offered through Plaid Check (Plaid's CRA subsidiary), provides the following:

**Base Report** for comprehensive bank account and cash flow data: See up to 24 months of consumer-permissioned bank account data (including account holder identity) along with categorized inflows and outflows. Get account-based attributes like balance averages and trends, as well as indicators of whether this is the borrower’s primary account based on transaction frequency.

**Income Insights** module for verification: Get details on over a dozen categorized income streams along with ready-made, model-driven attributes like historical gross and net income to streamline debt-to-income calculations and income verification. Assess financial stability with insights like forecasted income, employer name, income frequency, and predicted next payment date.

**Partner Insights** module for scores and attributes: Get off-the-shelf cash flow risk scores based on de-identified deposit account data. Offered through [Prism Data](https://prismdata.com) , these scores and attributes assess a consumer’s credit default risk and are available through a single integration and API call.

**Verification of Assets (VOA)** module: Designed specifically for mortgage lenders, VOA provides an FCRA-compliant asset verification report approved for use with Fannie Mae Day 1 Certainty. With VOA, lenders can validate asset balances, account ownership, and transaction behavior; submit reports to GSEs for rep and warrant relief; refresh reports for employment verification pre-close; and replace document uploads with a single Plaid Link session. VOA is currently in Early Availability; for more details, [contact Sales](https://plaid.com/check/consumer-report/#contact-form) or your Plaid Account Manager.

**Network Insights (beta)** module for connection history: With credit insights powered by the Plaid Network, customers get differentiated risk signals that are complementary to traditional credit and cash flow. Network Insights provides insights based on a user's connection history, including for services that aren't consistently reported to traditional credit bureaus, such as rent, buy-now-pay-later, cash advances, and earned wage access applications.

**Cash Flow Updates (beta)** module: Receive regular updates about changes to cash flow. See how income and loan exposure have changed for a borrower over time to improve post-decision servicing.

Plaid Check products are available only to US entities and can be used only to evaluate US consumers.

#### Integration overview 

If you already use one of Plaid's other products, see the product-specific migration guides for [Assets](https://plaid.com/docs/check/migrate-from-assets/index.html.md) , [Income](https://plaid.com/docs/check/migrate-from-income/index.html.md) , or [Transactions](https://plaid.com/docs/check/migrate-from-transactions/index.html.md) .

##### No-code integration with the Credit Dashboard 

The Credit Dashboard is currently in beta. To request access, contact your Account Manager.

Consumer Report data is available via a no-code integration through the [Credit Dashboard](https://dashboard.plaid.com/credit) . You can fill out a form with information about your end user, such as their name, email address, address, and phone number; and indicate your basis for processing this data and how much history you would like to collect. Plaid will then generate a hyperlink that can be used to launch a Plaid-hosted Link session. Plaid can email the link directly to your user (Production only, not available in Sandbox), or you can send it to them yourself.

After the end user successfully completes the Link session, their data will be available in the Dashboard for you to view, archive, or delete. The data shown will be the same data returned by a regular Consumer Report API call, in a user-friendly web-based session.

(An image of "Example dashboard credit report for end user, showing forecasted annual and monthly incomes. Income sources listed with types and frequency.")

Once you are enabled for the Credit Dashboard, all new sessions going forward, including ones created via the API, will be displayed in the Dashboard.

Data from Link sessions created via the Credit Dashboard cannot be accessed via the Plaid API. If you require programmatic access to data, use the code-based [Standard integration flow](https://plaid.com/docs/check/index.html.md#standard-integration-flow) instead.

##### Standard integration flow 

Below is a high-level integration overview. For detailed step-by-step instructions with sample code, see [Implementation](https://plaid.com/docs/check/add-to-app/index.html.md) .

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token`. You must include a `consumer_report_user_identity` object when calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . The user creation step will only need to be done once per end user.
    *   If you are already using the Plaid [Income](https://plaid.com/docs/income/index.html.md) product, you can update Income-compatible user tokens to be compatible with Consumer Reports by calling [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) and supplying the `consumer_report_user_identity` object.
2.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following:
    *   For `user_token`, provide the `user_token` you created in the previous step.
    *   For `products`, pass in `cra_base_report`, plus any additional Plaid Check products you wish to use (`cra_income_insights`, `cra_partner_insights`, and/or `cra_network_insights`), along with any additional Plaid Inc. products you are using. Note that Plaid Check products can't be used in the same Link flow with Income or Assets.
    *   Provide a `webhook` URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your reports are ready.
    *   Include the appropriate options for the products you are using in the `cra_options` object, including the required [days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-cra-options-days-requested) field.
    *   Include a `consumer_report_permissible_purpose` specifying your purpose for generating an insights report. If you do not include this field, the report will not be generated immediately, and you will instead need to call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) in order to trigger report creation.
    *   On mobile, specify the `redirect_uri` and/or `android_package_name` fields as necessary, per the relevant [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform.
    *   If you already have an existing Item and need to add Plaid Check to the Item, provide the Item's `access_token` in the `options.access_token` field. Otherwise, omit the `access_token` field in your request.
3.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
4.  Launch Link with the Link token and send the user through the Link flow. Once they have completed the flow and the report is ready, you will receive a [CHECK\_REPORT\_READY](https://plaid.com/docs/check/api/index.html.md#check_report_ready) webhook.
5.  Upon receiving the `CHECK_REPORT_READY` webhook, fetch the report data using an endpoint such as [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) , or [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) . This data must be fetched within 24 hours of report creation.
6.  (Optional) To refresh a Consumer Report with new data, call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to refresh the report. Upon refresh, a new `CHECK_REPORT_READY` webhook will fire and you can repeat the step above.

##### Cash Flow Updates integration 

To receive Cash Flow Updates (beta) on a Plaid Check-enabled user, follow the steps above, then perform the following additional steps:

1.  Call [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) , passing in the `user_token`.
2.  Listen for the [CRA\_MONITORING: INSIGHTS\_UPDATED](https://plaid.com/docs/api/products/check/index.html.md#insights_updated) webhook, which will be sent between one and four times a day for a user's Item.
3.  (Optional) You can also listen for specific webhooks that will be fired when certain events are detected: `LARGE_DEPOSIT_DETECTED`, `LOW_BALANCE_DETECTED`, `NEW_LOAN_PAYMENT_DETECTED`, and `NSF_OVERDRAFT_DETECTED`. For details, see [Cash Flow Updates webhooks](https://plaid.com/docs/api/products/check/index.html.md#cash-flow-updates-webhooks) .
4.  Call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights.
5.  (Optional) To stop receiving `INSIGHTS_UPDATED` webhooks for a user, call [/cra/monitoring\_insights/unsubscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsunsubscribe) .

##### Integrating with other Plaid products 

If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints. You can map accounts between Plaid CRA endpoints and Plaid endpoints by matching other fields such as `mask`, account `type` and `subtype`, and `institution_id`. If all of these fields match, and the accounts are associated with the same user in your records, the accounts are very likely the same.

##### Sharing reports with partners via OAuth 

To share a report with a partner such as Experian, Fannie Mae, or Freddie Mac, see [Share reports with partners](https://plaid.com/docs/check/oauth-sharing/index.html.md) .

#### Testing Consumer Report 

Access to Consumer Report in Sandbox is not granted by default. To request access, [contact Sales](https://plaid.com/check/consumer-report/#contact-form) or, for existing Plaid customers, contact your account manager or submit a [product access request](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) . Customers with [Production access to Consumer Report](https://dashboard.plaid.com/settings/team/product) will also automatically be granted Sandbox access.

To test Consumer Reports in the Sandbox environment, use the [Sandbox credit testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) for more realistic and valid data.

To use a [Sandbox custom user](https://plaid.com/docs/sandbox/user-custom/index.html.md) with Plaid Check, click "add new account" rather than using one of the existing banks. Using an existing bank in the Plaid Passport flow will skip the ability to enter a custom username.

##### Testing Cash Flow Updates 

After calling [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) , use the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) endpoint to manually trigger an update for Cash Flow Updates (Monitoring) in the Sandbox environment.

To avoid unexpected behavior when passing `LOW_BALANCE_DETECTED` in the `webhook_codes` field of the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) request body, use the default custom Sandbox user `user_good`.

#### Billing 

For details, see [Plaid Check fee model](https://plaid.com/docs/account/billing/index.html.md#plaid-check-fee-model) .

#### Next steps 

To get started building with Plaid Check, see [Add Consumer Report to your App](https://plaid.com/docs/check/add-to-app/index.html.md) .

If you're migrating from Assets, see the [Assets migration guide](https://plaid.com/docs/check/migrate-from-assets/index.html.md) .

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Consumer Report (by Plaid Check) - Migrate from Assets | Plaid Docs

Migrate from Asset Reports to Base Reports 
===========================================

#### Migrate to Base Reports to unlock access to the Consumer Report 

This guide will walk you through how to migrate from generating Asset Reports with Plaid's [Assets](https://plaid.com/products/assets/) product to generating Base Reports with Plaid Check's [Consumer Report](https://plaid.com/check/consumer-report/) product.

#### Prerequisites 

1.  To use Consumer Report, it is strongly recommended to update your Plaid client library to the latest version. The minimum required versions are:
    *   Python: 23.0.0
    *   Go: 26.0.0
    *   Java: 24.0.0
    *   Node: 25.0.0
    *   Ruby: 29.0.0
2.  [Confirm](https://dashboard.plaid.com/settings/team/products) that you have access to all required Plaid Check products in the Production environment. If you don't have access to Plaid Check, [request access via the Dashboard](https://dashboard.plaid.com/overview/request-products) . In order to migrate from Assets to Plaid Consumer Report, your end users must be in the US and you must be on a custom plan.

#### Changes to Plaid Link initialization 

When using Plaid Check products, you must create a user prior to sending the user through Link, and you must initialize Link with the resulting `user_token`. This allows Plaid to associate multiple Items with a single user.

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) prior to creating a Link token
    *   Include information about your user in the `consumer_report_user_identity` object
    *   Store the `user_id` and `user_token` in your database
2.  Update your call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate)
    *   Include the `user_token` string from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate)
    *   Replace the `assets` product string with `cra_base_report` in the `products` array
    *   Add a `cra_options` object and specify your desired `days_requested`
    *   Include a `consumer_report_permissible_purpose`
3.  (Optional) Unlike Assets, by default, Plaid Check includes only one linked Item per Report. To include multiple Items in a single Consumer Report, set `enable_multi_item_link` to `true` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request.

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

For more details, see the Plaid Check [Implementation guide](https://plaid.com/docs/check/add-to-app/index.html.md) .

##### Adding Consumer Report to existing Items 

To enable an existing Assets-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report.

#### Changes to post-Link integration 

Update your webhook listeners to listen for the new `CHECK_REPORT_READY` and `CHECK_REPORT_FAILED` webhooks.

*   Upon receiving a `CHECK_REPORT_READY` webhook, you should call [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , along with any other Consumer Report product endpoints that you would like to use.
*   Upon receiving a `CHECK_REPORT_FAILED` webhook, you should call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [Update Mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode) to repair them.

If you plan to continue using other Plaid Inc. products, such as [Auth](https://plaid.com/products/auth/) or [Balance](https://plaid.com/products/balance/) , you should continue to retrieve the public token and exchange it for an access token. If not, you no longer need to obtain an access token.

#### Mapping API responses 

Asset Reports and Base Reports have similar but not identical schemas. This [Google Sheet](https://docs.google.com/spreadsheets/d/1toj71Afemtu0rSjgh7AAGgBcZC7U0vYXKCDvKSSWTls/edit?usp=sharing) highlights their differences.

If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints.

---


# Consumer Report (by Plaid Check) - Migrate from Income | Plaid Docs

Migrate from Bank Income to Plaid Consumer Report 
==================================================

#### Switch to CRA Income Insights for model-driven income attributes and FCRA compliance 

This guide will walk you through how to migrate from accessing bank data with Plaid's [Bank Income](https://plaid.com/docs/income/index.html.md) product to generating Income Insights Reports with Plaid Check's Consumer Reports.

The CRA Income Insights Report offers model-driven attributes such as historical gross and net income, facilitating streamlined debt-to-income calculations and income verification. It enables assessment of financial stability through insights like forecasted income, employer name, income frequency, and predicted next payment date.

#### Advantages of Plaid Consumer Report 

Bank Income gives you net income data from both irregular or gig income and W-2 income. The CRA Income Insights Report enhances this by:

*   Providing FCRA-compliant insights
*   Bundling income calculations (historical average income, forecasted income, predicted next payment date) in a single report

Upgrading to Plaid Consumer Report is recommended for all Bank Income customers whose end users are based in the US. (CRA Income Insights is not available for end users outside the US.)

Income Insights does not replace Document Income or Payroll Income. Plaid Check products can't be used in the same Link flow as Plaid Inc. credit products such as Plaid Document Income, Payroll Income, Assets, or Statements. If you want to continue using any of those products, create separate [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests: one for Plaid Check products, and one for the Plaid Inc. credit products.

Non-credit Plaid products, such as Balance and Auth, can continue to be used in the same Link flow as Plaid Check products, and do not require any special changes to your integration.

#### Prerequisites 

1.  To use Consumer Report, it is strongly recommended to update your Plaid client library to the latest version. The minimum required versions are:
    
    *   Python: 23.0.0
    *   Go: 26.0.0
    *   Java: 24.0.0
    *   Node: 25.0.0
    *   Ruby: 29.0.0
2.  [Confirm](https://dashboard.plaid.com/settings/team/products) that you have access to all required Plaid Check products in the Production environment. If you don't have access to Plaid Check, [request access via the Dashboard](https://dashboard.plaid.com/overview/request-products) . In order to use Plaid Check, your end users must be in the US and you must be on a custom pricing plan.
    

#### Changes to Plaid Link initialization 

When using Plaid Check products, you must create a user prior to sending the user through Link and initialize Link with the resulting `user_token`. This allows Plaid to associate multiple Items with a single user.

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) prior to creating a Link token:
    
    *   Include identity info in the `consumer_report_user_identity` object. All fields are required except for `last_4_ssn`.
    *   Store the `user_id` and `user_token` in your database.
2.  Update your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request:
    
    *   Include the `user_token` string from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   In the `products` array, replace `income_verification` with `cra_base_report` and `cra_income_insights`.
    *   Remove the `income_verification` object.
    *   Add a `cra_options` object and specify `days_requested` (minimum 180).
    *   If you haven't already, set `webhook` to your webhook endpoint listener URL. Unlike Bank Income, Plaid Check requires the use of webhooks.
    *   Provide a `consumer_report_permissible_purpose`
    *   (Optional) To allow linking multiple Items in one session, set `enable_multi_item_link` to `true`.

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

For more details, see the Plaid Check [Implementation guide](https://plaid.com/docs/check/add-to-app/index.html.md) .

##### Adding Consumer Report to existing Items 

To enable an existing Income-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report.

#### Update product API calls and webhook listeners 

Unlike Bank Income, Plaid Check uses webhooks with async report generation.

1.  Add webhook listener endpoints for [CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#check_report_ready) and [CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#check_report_failed) .
    
    *   Upon receiving the [CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#check_report_ready) webhook, call product endpoints such as [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) .
    *   Upon receiving the [CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#check_report_failed) webhook, call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to repair the Item.
2.  Replace any Income endpoints and webhook listeners with the equivalent Plaid Check endpoint or webhook listener, using the [API response comparison sheet](https://docs.google.com/spreadsheets/d/1sjzpbPNjz0bF0Ndaly0tShMFgAZ2M9zdvBcQMlDKJbE/edit?gid=727344192#gid=727344192) to map response fields between the old endpoints and new endpoints.
    

| Income endpoint | Equivalent Plaid Check endpoint |
| --- | --- |
| [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) | None (remove) |
| [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) | [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) and/or [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) |
| [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) | [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget)  with `add_ons: ["cra_income_insights"]` |
| [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) | [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) |

| Income webhook | Equivalent Plaid Check webhook |
| --- | --- |
| `BANK_INCOME_REFRESH_COMPLETE` | `CHECK_REPORT_READY` |

#### API response comparison 

This [Google Sheet](https://docs.google.com/spreadsheets/d/1sjzpbPNjz0bF0Ndaly0tShMFgAZ2M9zdvBcQMlDKJbE/edit?gid=727344192#gid=727344192) highlights the correspondences between Bank Income and Plaid Check Income Insights schemas.

If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints.

---


# Consumer Report (by Plaid Check) - Migrate from Transactions | Plaid Docs

Migrate from Transactions to Plaid Consumer Report 
===================================================

#### Switch to CRA Base Report for FCRA-compliant reporting with enhanced data coverage. 

This guide will walk you through how to migrate from accessing bank data with Plaid's [Transactions](https://plaid.com/products/transactions/) product to generating Base Reports with Plaid's [Consumer Report](https://plaid.com/check/consumer-report/) product.

The CRA Base Report includes account balance, account ownership, and transaction data, and is designed for use cases that require FCRA-compliant consumer reporting, such as tenant screening, income verification, and credit decisioning.

#### Why migrate? 

While the Transactions product gives you historical transaction data, the CRA Base Report enhances this by:

*   Supporting FCRA-compliant usage
*   Bundling additional data (identity, balance, account metadata) in a single report
*   Managing the explicit consumer consent and disclosures required for underwriting use cases in the US

If your use case involves evaluating the financial standing of US-based end users for underwriting, credit, or leasing, you should use the CRA Base Report instead of Transactions.

#### Prerequisites 

1.  Update your Plaid SDK to the latest version. Minimum required versions:
    *   Python: 23.0.0
    *   Go: 26.0.0
    *   Java: 24.0.0
    *   Node: 25.0.0
    *   Ruby: 29.0.0
2.  [Confirm](https://dashboard.plaid.com/settings/team/products) you have access to Plaid Check products in Production. If not, [request access via the Dashboard](https://dashboard.plaid.com/overview/request-products) .

#### Changes to Plaid Link initialization 

When using Plaid Check products, you must create a user before initializing Link. This allows Plaid to associate multiple Items with a single user.

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) before [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate)
    *   Include `consumer_report_user_identity`.
    *   All fields are required except `last_4_ssn`.
    *   Store the `user_id` and `user_token` in your database.
2.  Update your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call:
    *   Remove the `transactions` object (if present) from the call.
    *   Include the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   Replace `transactions` with `cra_base_report` (and any other CRA products) in the `products` array.
    *   Add a `cra_options` object with `days_requested` (min 180).
    *   Provide a `consumer_report_permissible_purpose`.
    *   (Optional) To allow multi-institution linking, set `enable_multi_item_link` to `true`.

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Adding Consumer Report to existing Items 

To enable an existing Transactions-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report.

#### Changes to post-Link integration 

#### Update product API calls and webhook listeners 

1.  Update your webhook listener endpoints, adding listeners for Plaid Check.
    
    *   Upon receiving the [CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#check_report_ready) webhook, call product endpoints such as [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) or (if using) [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) .
        
    *   Upon receiving the [CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#check_report_failed) webhook, call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to repair the Item.
        

1.  If you're still using other Plaid products like [Auth](https://plaid.com/products/auth/) or [Balance](https://plaid.com/products/balance/) , continue retrieving and exchanging the public token. Otherwise, it's no longer needed.

#### Mapping API responses 

This [Google Sheet](https://docs.google.com/spreadsheets/d/1toj71Afemtu0rSjgh7AAGgBcZC7U0vYXKCDvKSSWTls/edit?gid=820738585#gid=820738585) highlights the correspondences between Transactions and CRA Base Report schemas.

If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints.

#### Migrating existing Items 

There is no way to directly migrate an existing Transactions-enabled Item to Plaid Check. Instead, you must delete the old Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and prompt the user to go through the Link flow again, using a Link token that is enabled for Plaid Check.

If you are ready to migrate all Items, use [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) to delete the Transactions-enabled Items, and prompt your users to return to your app to re-add their accounts using the new Plaid Check-enabled flow. You can also perform this process in stages, disabling only a percentage of Items at a time.

The most conservative gradual migration strategy is to not delete the Transactions-enabled Item until it is in an unhealthy state that requires user interaction to fix (e.g. `ITEM_LOGIN_REQUIRED`). At that time, instead of sending the Item through update mode, delete the Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and prompt your users to re-add their accounts using the new Plaid-Check enabled flow.

#### Removing Transactions logic for existing Items 

Depending on your use case and business, you may want to leave existing Transactions-enabled Items in place and perform a gradual migration, as described above. Do not remove Transactions logic unless you are no longer using any Transactions-enabled Items.

1.  Remove handling for Transactions webhooks, including `SYNC_UPDATES_AVAILABLE`, `INITIAL_UPDATE`, `HISTORICAL_UPDATE`, `DEFAULT_UPDATE`, `RECURRING_TRANSACTIONS_UPDATE`
    
2.  Remove calls to `/transactions/` endpoints such as [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , or [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) , as well as any handling for transactions-specific logic, such as transactions updates and pagination.
    
3.  Remove handling for the `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION` error.
    
4.  If you have existing Transactions-enabled Items you will no longer be using, call [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) to delete these Items so you will no longer be billed for Transactions.

---


# Consumer Report (by Plaid Check) | Plaid Docs

Sharing Consumer Report data with partners 
===========================================

#### Share Consumer Report data with approved partners using OAuth tokens 

#### Overview 

For eligible product use cases, Plaid Check provides the ability to share Consumer Reporting Agency (CRA) report information with approved partners (Fannie Mae, Freddie Mac, or Experian) using OAuth.

To share CRA report information with partners, you need to create an OAuth access token associated with a previously created user token that your partner can use to access the information.

#### Creating an OAuth token 

To create an access token that will be provided to your partner, call [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) following the example below.

For the `subject_token`, provide the `user_token` that you created using [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .

The `audience` must match the partner you are sharing with. Valid values are:

*   `urn:plaid:params:cra-partner:experian`
*   `urn:plaid:params:cra-partner:fannie-mae`
*   `urn:plaid:params:cra-partner:freddie-mac`

You can also provide multiple comma-separated values to create a token that will work with multiple partners. For example: `"audience": "urn:plaid:params:cra-partner:experian,urn:plaid:params:cra-partner:fannie-mae"`

```bash
curl 'https://sandbox.plaid.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "scope": "user:read",
  "subject_token_type":"urn:plaid:params:credit:multi-user",
  "audience": "urn:plaid:params:cra-partner:fannie-mae",
  "subject_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"
}'
```

```bash
{
  "access_token": "pda-RDdg0TUCB0FB25_UPIlnhA==",
  "expires_in": 2591999,
  "refresh_token": "Rpdr--viXurkDg88d5zf8m6Wl0g==",
  "request_id": "vPamXI8hYXPl7P2",
  "token_type": "Bearer"
}
```

You can then provide the `access_token` to your partner.

#### Revoking an OAuth token 

To revoke your token, call [/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) , passing in the `access_token` and/or `refresh_token` as the `token` value.

```bash
curl -X POST https://sandbox.plaid.com/oauth/revoke \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "token": "pda-RDdg0TUCB0FB25_UPIlnhA=="
}'
```

```bash
{
  "request_id": "pCDVCQK8ve2MzhM"
}
```

---


# Consumer Report (by Plaid Check) - Onboard users with Layer | Plaid Docs

Onboard users with Layer 
=========================

#### A guide to integrating Layer with Plaid Check 

#### Overview 

This guide will walk you through how to onboard users to Plaid Check with Layer. This process involves creating a user, onboarding the user with Layer, and retrieving the user's Plaid Check data.

#### Integration steps 

##### Create a user 

1.  Create a user token using the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. At this stage, the `consumer_report_user_identity` field is optional.

##### Onboard the user with Layer 

1.  Onboard the user by following Layer's [Integration Overview steps](https://plaid.com/docs/layer/index.html.md#integration-overview) .  
    When creating the Link token via [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) , pass in the user token you created and be sure the template used has CRA products enabled.
    
2.  Call [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) to retrieve user-permissioned identity information.
    
3.  After processing the identity information, update the Plaid user record by calling the [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) endpoint. Populate the `consumer_report_user_identity` field with the relevant information.
    

##### Retrieve the user's Plaid Check data 

1.  Now that the identity information has been added to the user record, you can generate a Consumer Report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) .
    
2.  Once the Consumer Report has been generated (indicated by a `CHECK_REPORT_READY` webhook), retrieve the report by calling [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) , or [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) .

---


# Enrich - Introduction to Enrich | Plaid Docs

Introduction to Enrich  
========================

#### Enrich your transaction data with merchant, category, and location insights. 

Get started with Enrich

[API Reference](https://plaid.com/docs/api/products/enrich/index.html.md)

#### Overview 

Enrich (US/CA only) makes it easy to work with transaction data generated by your own banking products or retrieved from other non-Plaid sources. Enrich brings context and meaning to your data by enriching it with detailed merchant, category, and location information. The enriched data can be used to build apps and features that help users manage their cash flow, earn rewards, and discover other financial products to help them reach their financial goals.

[Prefer to learn by watching? Get an overview of how Enrich works in just 3 minutes!](https://www.youtube.com/watch?v=2-iJtjzE_6U)

#### Sample Enrich data 

Below is an example of the enrichments Plaid can provide for a transaction.

```undefined
PURCHASE WM SUPERCENTER #1700 POWAY CAUS
```

```json
"counterparties": [{
   "name": "Walmart",
   "type": "merchant",
   "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
   "website": "walmart.com"
   "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM"
 }],
 "entity_id" : "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
 "location": {
   "address": "13425 Community Rd",
   "city": "Poway",
   "region": "CA",
   "country": "US",
   "postal_code": "92064",
   "store_number": "1700",
   "lat": 32.959068,
   "lon": -117.037666
 },
"logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
"merchant_name": "Walmart",
"payment_channel": "in store",
"personal_finance_category": {
  "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
  "primary": "GENERAL_MERCHANDISE",
},
"personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
"website": "walmart.com",
```

#### Testing Enrich 

Enrich is available for use in all environments.

Sandbox: Test the integration with sample transaction data. Send a request with data from this [preset list](https://plaid.com/documents/enrich_sandbox_preset_transactions.csv) of sample transactions to receive a response.

Production: Get real enrichments for all your transactions. Test in Limited Production for free.

*   If you don't yet have a Plaid plan, or are on a pay-as-you-go or growth plan, you can get access to Enrich by submitting a [Production request](https://dashboard.plaid.com/onboarding/) .
*   Existing Custom plan customers can self-enable for Enrich by agreeing to the terms of service in the [Dashboard](https://dashboard.plaid.com/settings/platform/enrich) .

When testing Enrich in Production, make sure to use input data and amounts that are as realistic as possible, as all input fields, not just `description`, are used to analyze transactions.

For more details and best practices on testing Enrich, see the [Enrich Testing Guide](https://plaid.docsend.com/view/8a4q6tx6jtm3qkih) .

#### Enrich integration process 

1.  Prepare your transaction data for enrichment. Plaid accepts a maximum of 100 transactions per request. For each transaction, include the `description`, `amount`, `direction`, `iso_currency_code` and `id`. For the best results, provide values in the optional `location`, `mcc`, and/or `date_posted` fields, if available.
2.  Call [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) to send Plaid your transactions.
3.  Plaid will provide an API response with all available enrichments for the transactions.

#### Enrich pricing 

Enrich is billed on a [flexible fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flexible-fee) ; you will be billed based on the number of transactions sent for enrichment. To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

---


# Errors - API errors | Plaid Docs

API Errors 
===========

#### Guide to troubleshooting API errors 

#### INTERNAL\_SERVER\_ERROR or plaid-internal-error 

##### Plaid was unable to process the request 

##### Sample user-facing error message 

Something went wrong: There was a problem and we couldn't connect your account. Try entering your username and password again.

##### Link user experience 

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

##### Common causes 

*   Plaid received an unsupported response from a financial institution, which frequently corresponds to an [institution](https://plaid.com/docs/errors/institution/index.html.md) error.
*   Plaid is experiencing internal system issues.
*   A product endpoint request was made for an Item at an OAuth-based institution, but the end user did not authorize the Item for the specific product, or has revoked Plaid's access to the product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account.

##### Troubleshooting steps 

If the error persists, please submit a [Support](https://dashboard.plaid.com/support/new/) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 500
{
 "error_type": "API_ERROR",
 "error_code": "INTERNAL_SERVER_ERROR",
 "error_message": "an unexpected error occurred",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PLANNED\_MAINTENANCE 

##### Plaid's systems are undergoing maintenance and API operations are disabled 

##### Sample user-facing error message 

Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time

##### Link user experience 

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

##### Common causes 

*   Plaid's systems are under maintenance and API operations are temporarily disabled. Advance notice will be provided when a maintenance window is planned.

##### Troubleshooting steps 

If you have not been previously informed of planned maintenance, please reach out to Plaid [Support](https://dashboard.plaid.com/support/new/) for more information.

API error responseLink error preview

```json
http code 503
{
 "error_type": "API_ERROR",
 "error_code": "PLANNED_MAINTENANCE",
 "error_message": "the Plaid API is temporarily unavailable due to planned maintenance. visit https://status.plaid.com/ for more information",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Assets errors | Plaid Docs

Assets Errors 
==============

#### Guide to troubleshooting Assets errors 

#### PRODUCT\_NOT\_ENABLED 

##### Common causes 

*   One or more of the Items in the Asset Report was not initialized with the Assets product. Unlike some products, Assets cannot be initialized "on-the-fly" and must be initialized during the initial link process.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "PRODUCT_NOT_ENABLED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### DATA\_UNAVAILABLE 

##### Common causes 

*   One or more of the Items in the Asset Report has experienced an error.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "DATA_UNAVAILABLE",
 "error_message": "unable to pull sufficient data for all items to generate this report. please see the \"causes\" field for more details",
 "display_message": null,
 "causes": [
  {
   "display_message": null,
   "error_code": "ITEM_LOGIN_REQUIRED",
   "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
   "error_type": "ITEM_ERROR",
   "item_id": "pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F"
  }
 ],
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCT\_NOT\_READY 

Note that this error should not be confused with the [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error of type `ITEM_ERROR`, which has different causes.

##### Common causes 

*   [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) was called before the Asset Report generation completed.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "PRODUCT_NOT_READY",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ASSET\_REPORT\_GENERATION\_FAILED 

##### Common causes 

*   Plaid is experiencing temporary difficulties generating Asset Reports.
*   The Asset Report was too large to generate.

##### Troubleshooting steps 

If the error persists, please submit a [Support](https://dashboard.plaid.com/support/new/) ticket.

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "ASSET_REPORT_GENERATION_FAILED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_PARENT 

##### Common causes 

*   An endpoint that creates a copy or modified copy of an Asset Report (such as [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) or [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) ) was called, but the original Asset Report does not exist, either because it was never successfully created in the first place or because it was deleted.

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "INVALID_PARENT",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSIGHTS\_NOT\_ENABLED 

##### Common causes 

*   [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) was called with `enable_insights` set to `true` by a Plaid developer account that has not been enabled for access to Asset Reports with Insights.

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "INSIGHTS_NOT_ENABLED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSIGHTS\_PREVIOUSLY\_NOT\_ENABLED 

##### Common causes 

*   [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) was called with `enable_insights` set to `true` by a Plaid developer account that is currently enabled for Asset Reports with Insights, but was not enabled at the time that the report was created.

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "INSIGHTS_PREVIOUSLY_NOT_ENABLED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### DATA\_QUALITY\_CHECK\_FAILED 

##### Common causes 

*   The extracted data from the financial institution showed signs of poor data quality, preventing the generation of an accurate report.

```json
http code 400
{
 "error_type": "ASSET_REPORT_ERROR",
 "error_code": "DATA_QUALITY_CHECK_FAILED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Check Report errors | Plaid Docs

Check Report Errors 
====================

#### Guide to troubleshooting Check Report errors 

#### CONSUMER\_REPORT\_EXPIRED 

##### Common causes 

*   The Check Report has expired as 24 hours have passed since its creation, so it is no longer retrievable.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CONSUMER_REPORT_ERROR",
 "error_code": "CONSUMER_REPORT_EXPIRED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### DATA\_UNAVAILABLE 

##### Common causes 

*   Plaid Check failed to retrieve data from the user's financial institutions to generate Check Report product data.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CHECK_REPORT_ERROR",
 "error_code": "DATA_UNAVAILABLE",
 "error_message": "The Check Report you are trying to pull does not have sufficient transactions data to generate a report.",
 "display_message": null,
 "causes": [
  {
   "display_message": null,
   "error_code": "ITEM_LOGIN_REQUIRED",
   "error_message": "The login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
   "error_type": "ITEM_ERROR",
   "item_id": "pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F"
  }
 ],
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCT\_NOT\_READY 

Note that this error should not be confused with the [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error of type `ITEM_ERROR`, which has different causes.

##### Common causes 

*   `/check_report/.../get` was called before report generation completed.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CONSUMER_REPORT_ERROR",
 "error_code": "PRODUCT_NOT_READY",
 "error_message": "The consumer report you are trying to pull is not ready. Please wait for a CHECK_REPORT_READY webhook to fetch data",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_TRANSACTION\_HISTORY\_NOT\_SUPPORTED 

##### Common causes 

*   The user's financial institution does not support the length of transaction history you require

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CHECK_REPORT_ERROR",
 "error_code": "INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED",
 "error_message": "The user’s bank does not support the transactions range you require. Lowering the days_required may result in success.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSUFFICIENT\_TRANSACTION\_DATA 

##### Common causes 

*   The user does not have sufficient transactions data to generate income insights, partner insights, or cashflow insights. The `error_message` will provide more detail on what data is missing.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CHECK_REPORT_ERROR",
 "error_code": "INSUFFICIENT_TRANSACTION_DATA",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_ACCOUNTS 

##### Common causes 

*   The user does not the correct accounts linked to generate income insights. The `error_message` will provide more detail on what data is missing.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CHECK_REPORT_ERROR",
 "error_code": "NO_ACCOUNTS",
 "error_message": "No depository accounts were found for this user",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NETWORK\_CONSENT\_REQUIRED 

##### Common causes 

*   The user did not provide consent in link to share Plaid network data.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "CHECK_REPORT_ERROR",
 "error_code": "NETWORK_CONSENT_REQUIRED",
 "error_message": "User has not provided consent to share network data",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Income errors | Plaid Docs

Income errors 
==============

#### Guide to troubleshooting Income errors 

#### INCOME\_VERIFICATION\_DOCUMENT\_NOT\_FOUND 

##### The requested income verification document was not found. 

##### Common causes 

*   The document URL is incorrect (for example, it may contain a typo) or has expired.
*   The document URL has already been accessed. Document URLs can only be used once.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "INCOME_VERIFICATION_DOCUMENT_NOT_FOUND",
 "error_message": "the requested data was not found. Please check the ID supplied.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INCOME\_VERIFICATION\_FAILED 

##### The income verification you are trying to retrieve could not be completed. please try creating a new income verification 

##### Common causes 

*   The processing of the verification failed to complete successfully.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "INCOME_VERIFICATION_FAILED",
 "error_message": "the income verification you are trying to retrieve could not be completed. please try creating a new income verification",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INCOME\_VERIFICATION\_NOT\_FOUND 

##### The requested income verification was not found. 

##### Common causes 

*   The Link flow has not been completed with `income_verification` enabled; either the user has not yet completed the Link flow, or the link token was not initialized with the `income_verification` product.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "INCOME_VERIFICATION_NOT_FOUND",
 "error_message": "the requested data was not found. Please check the ID supplied.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INCOME\_VERIFICATION\_UPLOAD\_ERROR 

##### There was an error uploading income verification documents. 

##### Common causes 

*   The end user's Internet connection may have been interrupted during the upload attempt.

##### Troubleshooting steps 

```json
http code 500
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "INCOME_VERIFICATION_UPLOAD_ERROR",
 "error_message": "there was a problem uploading the document for verification. Please try again or recreate an income verification.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCT\_NOT\_ENABLED 

##### The Income product has not been enabled. 

##### Common causes 

*   The Income product has not been enabled.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "PRODUCT_NOT_ENABLED",
 "error_message": "the 'income_verification' product is not enabled for the following client ID: . please ensure that the 'income_verification' is included in the 'product' array when initializing Link and try again.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCT\_NOT\_READY 

##### The Income product has not completed processing. 

##### Common causes 

*   Parsing of the uploaded pay stubs has not yet completed.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "PRODUCT_NOT_READY",
 "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### VERIFICATION\_STATUS\_PENDING\_APPROVAL 

##### The user has not yet authorized the sharing of this data 

##### Common causes 

*   The user has not yet authorized access to the data.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "VERIFICATION_STATUS_PENDING_APPROVAL",
 "error_message": "The user has not yet authorized the sharing of this data",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### EMPLOYMENT\_NOT\_FOUND 

##### The requested employment was not found. 

##### Common causes 

*   The Link flow has not been completed with `employment` enabled; either the user has not yet completed the Link flow, or the link token was not initialized with the `employment` product.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INCOME_VERIFICATION_ERROR",
 "error_code": "EMPLOYMENT_NOT_FOUND",
 "error_message": "the requested employment data was not found. Please check the ID supplied.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Overview | Plaid Docs

Errors 
=======

#### A comprehensive breakdown of all Plaid error codes 

#### Most common errors 

The following are the most common errors that may occur in response to an API call even if your implementation is correct. This list of common errors excludes Item errors that occur only during the Link flow (typically due to bad data entry by the end user), such as [INVALID\_CREDENTIALS](https://plaid.com/docs/errors/item/index.html.md#invalid_credentials) , and errors that can occur only due to sending invalid input, such as [INVALID\_FIELD](https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field) . It is recommended that your integration should, at minimum, handle each of the errors below that are applicable to your product and/or integration mode.

In the table below, "institution-based products" refers to any product or integration that connects to a bank or other financial institution (i.e., most Plaid products); it excludes products such as Identity Verification, Monitor, Enrich, and Document Income that do not involve making a connection to a financial institution.

| Error | Applies to | Summary |
| --- | --- | --- |
| [ITEM\_LOGIN\_REQUIRED](https://plaid.com/docs/errors/item/index.html.md#item_login_required) | All institution-based products | Item has expired credentials or consent |
| [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) | Signal, Assets, Income, Check, Auth, [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | Plaid hasn't finished obtaining the data needed to fulfill your request |
| [PRODUCTS\_NOT\_SUPPORTED](https://plaid.com/docs/errors/item/index.html.md#products_not_supported) | All institution-based products | The product endpoint isn't compatible with this Item |
| [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) | [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | An update was received during Transactions pagination |
| [NO\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_accounts) | All institution-based products | Couldn't find any open accounts |
| [NO\_AUTH\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_auth_accounts-or-no-depository-accounts) | Auth | Couldn't find any debitable checking, savings, or cash management accounts |
| [NO\_LIABILITY\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_liability_accounts) | Liabilities | Couldn't find any credit accounts |
| [NO\_INVESTMENT\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_investment_accounts) | Investments | Couldn't find any investment accounts |
| [ACCESS\_NOT\_GRANTED](https://plaid.com/docs/errors/item/index.html.md#access_not_granted) | All institution-based products | The end user didn't grant an OAuth permission required for your request |
| [ADDITIONAL\_CONSENT\_REQUIRED](https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required) | Integrations in the US or Canada that [add products to Items after Link](https://plaid.com/docs/link/initializing-products/index.html.md#adding-products-post-link) | The end user didn't grant a data scope required for your request |
| [INSTITUTION\_NOT\_RESPONDING](https://plaid.com/docs/errors/institution/index.html.md#institution_not_responding) | All institution-based products | Temporary financial institution connectivity outage |
| [INSTITUTION\_DOWN](https://plaid.com/docs/errors/institution/index.html.md#institution_down) | All institution-based products | Temporary financial institution connectivity outage |
| [RATE\_LIMIT\_EXCEEDED](https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md) | Applications that batch-process Plaid API calls or have heavy traffic spikes | Too many requests made too quickly, or Limited Production caps hit |
| [INTERNAL\_SERVER\_ERROR](https://plaid.com/docs/errors/api/index.html.md#internal_server_error-or-plaid-internal-error) | All products | Internal error or financial institution error not otherwise specified |

#### Errors overview 

<table class="Container_table__oZo8c"><tbody><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Item errors</div><div class="Row_subtitle__8_gRf">Occur when an Item may be invalid or not supported on Plaid's platform.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#access_not_granted">ACCESS_NOT_GRANTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#instant_match_failed">INSTANT_MATCH_FAILED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#insufficient_credentials">INSUFFICIENT_CREDENTIALS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#invalid_credentials">INVALID_CREDENTIALS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#invalid_mfa">INVALID_MFA</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#invalid_otp">INVALID_OTP</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#invalid_phone_number">INVALID_PHONE_NUMBER</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#invalid_send_method">INVALID_SEND_METHOD</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#invalid_updated_username">INVALID_UPDATED_USERNAME</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#item_concurrently_deleted">ITEM_CONCURRENTLY_DELETED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#item_locked">ITEM_LOCKED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#item_login_required">ITEM_LOGIN_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#item_not_found">ITEM_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#item_not_supported">ITEM_NOT_SUPPORTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#mfa_not_supported">MFA_NOT_SUPPORTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#no_accounts">NO_ACCOUNTS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#no_auth_accounts-or-no-depository-accounts">NO_AUTH_ACCOUNTS </a></span><span class="ContentItem_description__a1WXd">or no-depository-accounts</span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#no_investment_accounts">NO_INVESTMENT_ACCOUNTS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#no_investment_auth_accounts">NO_INVESTMENT_AUTH_ACCOUNTS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#no_liability_accounts">NO_LIABILITY_ACCOUNTS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#password_reset_required">PASSWORD_RESET_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#product_not_enabled">PRODUCT_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#product_not_ready">PRODUCT_NOT_READY</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#products_not_supported">PRODUCTS_NOT_SUPPORTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#user_input_timeout">USER_INPUT_TIMEOUT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/item/index.html.md#user_setup_required">USER_SETUP_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Institution errors</div><div class="Row_subtitle__8_gRf">Occur when there are errors for the requested financial institution.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#institution_down">INSTITUTION_DOWN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#institution_no_longer_supported">INSTITUTION_NO_LONGER_SUPPORTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#institution_not_available">INSTITUTION_NOT_AVAILABLE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#institution_not_enabled_in_environment">INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#institution_not_responding">INSTITUTION_NOT_RESPONDING</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#institution_registration_required">INSTITUTION_REGISTRATION_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#unauthorized_institution">UNAUTHORIZED_INSTITUTION</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/institution/index.html.md#unsupported_response">UNSUPPORTED_RESPONSE</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">API errors</div><div class="Row_subtitle__8_gRf">Occur during planned maintenance and in response to API errors.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/api/index.html.md#internal_server_error-or-plaid-internal-error">INTERNAL_SERVER_ERROR </a></span><span class="ContentItem_description__a1WXd">or plaid-internal-error</span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/api/index.html.md#planned_maintenance">PLANNED_MAINTENANCE</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Assets errors</div><div class="Row_subtitle__8_gRf">Occur for errors related to Asset endpoints.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#product_not_enabled">PRODUCT_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#data_unavailable">DATA_UNAVAILABLE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#product_not_ready">PRODUCT_NOT_READY</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#asset_report_generation_failed">ASSET_REPORT_GENERATION_FAILED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#invalid_parent">INVALID_PARENT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#insights_not_enabled">INSIGHTS_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#insights_previously_not_enabled">INSIGHTS_PREVIOUSLY_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/assets/index.html.md#data_quality_check_failed">DATA_QUALITY_CHECK_FAILED</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Payment errors</div><div class="Row_subtitle__8_gRf">Occur for errors related to Payment Initiation endpoints.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_blocked">PAYMENT_BLOCKED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_cancelled">PAYMENT_CANCELLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_insufficient_funds">PAYMENT_INSUFFICIENT_FUNDS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_invalid_recipient">PAYMENT_INVALID_RECIPIENT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_invalid_reference">PAYMENT_INVALID_REFERENCE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_invalid_schedule">PAYMENT_INVALID_SCHEDULE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_rejected">PAYMENT_REJECTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_scheme_not_supported">PAYMENT_SCHEME_NOT_SUPPORTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_consent_invalid_constraints">PAYMENT_CONSENT_INVALID_CONSTRAINTS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/payment/index.html.md#payment_consent_cancelled">PAYMENT_CONSENT_CANCELLED</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Virtual Account errors</div><div class="Row_subtitle__8_gRf">Occur for errors related to Virtual Account endpoints.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_insufficient_funds">TRANSACTION_INSUFFICIENT_FUNDS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_amount_exceeded">TRANSACTION_AMOUNT_EXCEEDED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_on_same_account">TRANSACTION_ON_SAME_ACCOUNT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_currency_mismatch">TRANSACTION_CURRENCY_MISMATCH</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_iban_invalid">TRANSACTION_IBAN_INVALID</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_bacs_invalid">TRANSACTION_BACS_INVALID</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_fast_pay_disabled">TRANSACTION_FAST_PAY_DISABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#transaction_execution_failed">TRANSACTION_EXECUTION_FAILED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#nonidentical_request">NONIDENTICAL_REQUEST</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/virtual-account/index.html.md#request_conflict">REQUEST_CONFLICT</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Transactions errors</div><div class="Row_subtitle__8_gRf">Occur for errors related to Transactions endpoints.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination">TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Transfer errors</div><div class="Row_subtitle__8_gRf">Occur for errors related to Transfer endpoints.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_network_limit_exceeded">TRANSFER_NETWORK_LIMIT_EXCEEDED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_account_blocked">TRANSFER_ACCOUNT_BLOCKED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_not_cancellable">TRANSFER_NOT_CANCELLABLE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_unsupported_account_type">TRANSFER_UNSUPPORTED_ACCOUNT_TYPE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_forbidden_ach_class">TRANSFER_FORBIDDEN_ACH_CLASS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_ui_unauthorized">TRANSFER_UI_UNAUTHORIZED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#transfer_originator_not_found">TRANSFER_ORIGINATOR_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#incomplete_customer_onboarding">INCOMPLETE_CUSTOMER_ONBOARDING</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/transfer/index.html.md#unauthorized_access">UNAUTHORIZED_ACCESS</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Income errors</div><div class="Row_subtitle__8_gRf">Occur for errors related to Income endpoints.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#income_verification_document_not_found">INCOME_VERIFICATION_DOCUMENT_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#income_verification_failed">INCOME_VERIFICATION_FAILED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#income_verification_not_found">INCOME_VERIFICATION_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#income_verification_upload_error">INCOME_VERIFICATION_UPLOAD_ERROR</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#product_not_enabled">PRODUCT_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#product_not_ready">PRODUCT_NOT_READY</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#verification_status_pending_approval">VERIFICATION_STATUS_PENDING_APPROVAL</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/income/index.html.md#employment_not_found">EMPLOYMENT_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Sandbox errors</div><div class="Row_subtitle__8_gRf">Occur when invalid parameters are supplied in the Sandbox environment.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/sandbox/index.html.md#sandbox_product_not_enabled">SANDBOX_PRODUCT_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/sandbox/index.html.md#sandbox_webhook_invalid">SANDBOX_WEBHOOK_INVALID</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/sandbox/index.html.md#sandbox_transfer_event_transition_invalid">SANDBOX_TRANSFER_EVENT_TRANSITION_INVALID</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Invalid Request errors</div><div class="Row_subtitle__8_gRf">Occur when a request is malformed and cannot be processed.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#missing_fields">MISSING_FIELDS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#unknown_fields">UNKNOWN_FIELDS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field">INVALID_FIELD</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_configuration">INVALID_CONFIGURATION</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#incompatible_api_version">INCOMPATIBLE_API_VERSION</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_body">INVALID_BODY</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_headers">INVALID_HEADERS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#not_found">NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#no_longer_available">NO_LONGER_AVAILABLE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#sandbox_only">SANDBOX_ONLY</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_account_number">INVALID_ACCOUNT_NUMBER</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Invalid Input errors</div><div class="Row_subtitle__8_gRf">Occur when all fields are provided, but the values provided are incorrect in some way.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required">ADDITIONAL_CONSENT_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#direct_integration_not_enabled">DIRECT_INTEGRATION_NOT_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#incorrect_deposit_verification">INCORRECT_DEPOSIT_VERIFICATION</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_access_token">INVALID_ACCESS_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_account_id">INVALID_ACCOUNT_ID</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_api_keys">INVALID_API_KEYS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_audit_copy_token">INVALID_AUDIT_COPY_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_institution">INVALID_INSTITUTION</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_link_customization">INVALID_LINK_CUSTOMIZATION</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_processor_token">INVALID_PROCESSOR_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_product">INVALID_PRODUCT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_public_token">INVALID_PUBLIC_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_link_token">INVALID_LINK_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_stripe_account">INVALID_STRIPE_ACCOUNT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_user_token">INVALID_USER_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_webhook_verification_key_id">INVALID_WEBHOOK_VERIFICATION_KEY_ID</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#unauthorized_environment">UNAUTHORIZED_ENVIRONMENT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#unauthorized_route_access">UNAUTHORIZED_ROUTE_ACCESS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#user_permission_revoked">USER_PERMISSION_REVOKED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-input/index.html.md#too_many_verification_attempts">TOO_MANY_VERIFICATION_ATTEMPTS</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Invalid Result errors</div><div class="Row_subtitle__8_gRf">Occur when a request is valid, but the output would be unusable for any supported flow.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/invalid-result/index.html.md#plaid_direct_item_import_returned_invalid_mfa">PLAID_DIRECT_ITEM_IMPORT_RETURNED_INVALID_MFA</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Rate Limit Exceeded errors</div><div class="Row_subtitle__8_gRf">Occur when an excessive number of requests are made in a short period of time.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#accounts_limit">ACCOUNTS_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#accounts_balance_get_limit">ACCOUNTS_BALANCE_GET_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#auth_limit">AUTH_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#balance_limit">BALANCE_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#credits_exhausted">CREDITS_EXHAUSTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#identity_limit">IDENTITY_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#institutions_get_limit">INSTITUTIONS_GET_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#institutions_get_by_id_limit">INSTITUTIONS_GET_BY_ID_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#institution_rate_limit">INSTITUTION_RATE_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#investment_holdings_get_limit">INVESTMENT_HOLDINGS_GET_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#investment_transactions_limit">INVESTMENT_TRANSACTIONS_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#item_get_limit">ITEM_GET_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#rate_limit">RATE_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#transactions_limit">TRANSACTIONS_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md#transactions_sync_limit">TRANSACTIONS_SYNC_LIMIT</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">ReCAPTCHA errors</div><div class="Row_subtitle__8_gRf">Occur when a ReCAPTCHA challenge has been presented or failed during the link process.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/recaptcha/index.html.md#recaptcha_required">RECAPTCHA_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/recaptcha/index.html.md#recaptcha_bad">RECAPTCHA_BAD</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">OAuth errors</div><div class="Row_subtitle__8_gRf">Occur when there is an error in OAuth authentication.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/oauth/index.html.md#incorrect_oauth_nonce">INCORRECT_OAUTH_NONCE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/oauth/index.html.md#incorrect_link_token">INCORRECT_LINK_TOKEN</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/oauth/index.html.md#oauth_state_id_already_processed">OAUTH_STATE_ID_ALREADY_PROCESSED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/oauth/index.html.md#oauth_state_id_not_found">OAUTH_STATE_ID_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Micro-deposits errors</div><div class="Row_subtitle__8_gRf">Occur when there is an error with micro-deposits.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/microdeposits/index.html.md#bank_transfer_account_blocked">BANK_TRANSFER_ACCOUNT_BLOCKED</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Partner errors</div><div class="Row_subtitle__8_gRf">Occur when there is an error with creating or managing end customers.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#customer_not_found">CUSTOMER_NOT_FOUND</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#flowdown_not_complete">FLOWDOWN_NOT_COMPLETE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#questionnaire_not_complete">QUESTIONNAIRE_NOT_COMPLETE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#customer_not_ready_for_enablement">CUSTOMER_NOT_READY_FOR_ENABLEMENT</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#customer_already_enabled">CUSTOMER_ALREADY_ENABLED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#customer_already_created">CUSTOMER_ALREADY_CREATED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#logo_required">LOGO_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#invalid_logo">INVALID_LOGO</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#contact_required">CONTACT_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#assets_under_management_required">ASSETS_UNDER_MANAGEMENT_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/partner/index.html.md#customer_removal_not_allowed">CUSTOMER_REMOVAL_NOT_ALLOWED</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Check Report errors</div><div class="Row_subtitle__8_gRf">Occur when there is an error with creating or retrieving a Check Report.</div></td><td class="Row_contents__EJTwh"><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#consumer_report_expired">CONSUMER_REPORT_EXPIRED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#data_unavailable">DATA_UNAVAILABLE</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#product_not_ready">PRODUCT_NOT_READY</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#institution_transaction_history_not_supported">INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#insufficient_transaction_data">INSUFFICIENT_TRANSACTION_DATA</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#no_accounts">NO_ACCOUNTS</a></span><span class="ContentItem_description__a1WXd"></span></div><div class="ContentItem_container__yMF3S"><span class="ContentItem_link___vx_v Error_error__1d_2c"><a href="https://plaid.com/docs/errors/check-report/index.html.md#network_consent_required">NETWORK_CONSENT_REQUIRED</a></span><span class="ContentItem_description__a1WXd"></span></div></td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0"></div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh"></td></tr></tbody></table>

\=\*=\*=\*=

#### Error schema 

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](https://plaid.com/docs/api/items/index.html.md#itemget) 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.

**Properties**

[error\_type](https://plaid.com/docs/errors/index.html.md#PlaidError-error-type)

string

A broad categorization of the error. Safe for programmatic use.  
  

Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`

[error\_code](https://plaid.com/docs/errors/index.html.md#PlaidError-error-code)

string

The particular error code. Safe for programmatic use.

[error\_code\_reason](https://plaid.com/docs/errors/index.html.md#PlaidError-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](https://plaid.com/docs/errors/index.html.md#PlaidError-error-message)

string

A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

[display\_message](https://plaid.com/docs/errors/index.html.md#PlaidError-display-message)

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](https://plaid.com/docs/errors/index.html.md#PlaidError-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](https://plaid.com/docs/errors/index.html.md#PlaidError-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](https://plaid.com/docs/errors/index.html.md#PlaidError-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](https://plaid.com/docs/errors/index.html.md#PlaidError-documentation-url)

string

The URL of a Plaid documentation page with more information about the error

[suggested\_action](https://plaid.com/docs/errors/index.html.md#PlaidError-suggested-action)

string

Suggested steps for resolving the error

---


# Errors - Institution errors | Plaid Docs

Institution Errors 
===================

#### Guide to troubleshooting Institution errors 

#### INSTITUTION\_DOWN 

##### The financial institution is down, either for maintenance or due to an infrastructure issue with their systems. 

##### Sample user-facing error message 

Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time

##### Link user experience 

Your user will be redirected to the `Institution Select` pane to retry connecting their Item or a different account.

##### Common causes 

*   The institution is undergoing scheduled maintenance.
*   The institution is experiencing temporary technical problems.

##### Troubleshooting steps 

If the error persists, please submit a 'Persistent HTTP 500 errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/persistent-500) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_DOWN",
 "error_message": "this institution is not currently responding to this request. please try again soon",
 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_NOT\_ENABLED\_IN\_ENVIRONMENT 

##### Institution not enabled in this environment 

##### Common causes 

You're referencing an institution that exists, but is not enabled for this environment (e.g. calling a Sandbox endpoint with the ID of an institution that is not enabled there).

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT",
 "error_message": "Institution not enabled in this environment",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_NOT\_RESPONDING 

##### The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time. 

##### Sample user-facing error message 

Couldn't connect to your institution: If you need to use this app immediately, we recommend trying another institution. Errors like this are usually resolved quickly, so you may want to try the same account again later.

##### Link user experience 

Your user will be redirected to the `Institution Select` pane to retry connecting their Item or a different account.

##### Common causes 

*   The institution is experiencing temporary technical problems.

##### Troubleshooting steps 

If the error persists, please submit a 'Persistent HTTP 500 errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/persistent-500) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_NOT_RESPONDING",
 "error_message": "this institution is not currently responding to this request. please try again soon",
 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_NOT\_AVAILABLE 

##### The financial institution is not available this time. 

##### Link user experience 

Your user will be redirected to the `Institution Select` pane to retry connecting their Item or a different account.

##### Common causes 

*   Plaid’s connection to an institution is temporarily down for maintenance or other planned circumstances.

##### Troubleshooting steps 

If the error persists, please submit a 'Persistent HTTP 500 errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/persistent-500) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_NOT_AVAILABLE",
 "error_message": "this institution is not currently responding to this request. please try again soon",
 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_NO\_LONGER\_SUPPORTED 

##### Plaid no longer supports this financial institution. 

##### Sample user-facing error message 

Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time.

##### Common causes 

*   The financial institution is no longer supported on Plaid's platform.
*   The institution has switched from supporting non-OAuth-based connections to requiring OAuth-based connections.

API error responseLink error preview

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_NO_LONGER_SUPPORTED",
 "error_message": "this institution is no longer supported",
 "display_message": "This financial institution is no longer supported. We apologize for the inconvenience.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### UNAUTHORIZED\_INSTITUTION 

##### You are not authorized to create Items for this institution at this time. 

##### Common causes 

*   Access to this institution is subject to additional verification and must be manually enabled for your account.
*   You have not yet completed the OAuth registration requirements for the institution.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "UNAUTHORIZED_INSTITUTION",
 "error_message": "not authorized to create items for this institution",
 "display_message": "You are not authorized to create items for this institution at this time.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_REGISTRATION\_REQUIRED 

##### Your application is not yet registered with the institution. 

##### Common causes 

*   Details about your application must be registered with this institution before use.
*   If your account has not yet been enabled for Production access, some institutions that require registration may not be available to you.
*   You have not completed the Security Questionnaire.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_REGISTRATION_REQUIRED",
 "error_message": "not yet registered to create items for this institution",
 "display_message": "You must register your application with this institution before you can create items for it.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### UNSUPPORTED\_RESPONSE 

##### The data returned from the financial institution is not valid. 

##### Common causes 

*   The data returned from the financial institution is not supported or is invalid.

```json
http code 400
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "UNSUPPORTED_RESPONSE",
 "error_message": "the data returned from the financial institution is not valid",
 "display_message": "The data returned from the financial institution is not valid.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Invalid Input errors | Plaid Docs

Invalid Input Errors 
=====================

#### Guide to troubleshooting invalid input errors 

#### DIRECT\_INTEGRATION\_NOT\_ENABLED 

##### An attempt was made to create an Item without using Link. 

##### Common causes 

*   `/item/create` was called directly, without using Link.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "DIRECT_INTEGRATION_NOT_ENABLED",
 "error_message": "your client ID is only authorized to use Plaid Link. head to the docs (https://plaid.com/docs) to get started.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INCORRECT\_DEPOSIT\_VERIFICATION 

##### The user submitted an incorrect Manual Same-Day micro-deposit verification input during Item verification in Link. 

##### Sample user-facing error message 

Code is incorrect, 2 attempts remaining: Check the bank statement of your account ending in •••0000 for the $0.01 deposit and try again.

##### Common causes 

*   Your user submitted an incorrect micro-deposit verification input when verifying an account via Manual Same-Day micro-deposits.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INCORRECT_DEPOSIT_VERIFICATION",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_ACCESS\_TOKEN 

##### Common causes 

*   Access tokens are in the format: `access-<environment>-<identifier>`
*   This error can happen when the `access_token` you provided is invalid or pertains to a different API environment

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_ACCESS_TOKEN",
 "error_message": "could not find matching access token",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_ACCOUNT\_ID 

##### The supplied account\_id is not valid 

##### Common causes 

One of the `account_id`(s) specified in the API call's `account_ids` object is invalid or does not exist.

*   Your integration is passing a correctly formatted, but invalid `account_id` for the Item in question.
*   The underlying account may have been closed at the bank, and thus removed from our API.
*   The Item affected is at an institution that uses OAuth-based connections, and the user revoked access to the specific account.
*   The `account_id` was removed from our API, either completely or a new `account_id` was assigned to the same underlying account.
*   You are requesting an account that your user has de-selected in the Account Select v2 update flow.

##### Troubleshooting steps 

Ensure that your integration only uses `account_id`(s) that belong to the Item in question. Early on in your development it is important to verify that your integration only uses `account_id`(s), and other Plaid identifiers like `item_id`, for the Item that they belong to.

Also be sure to preserve the case of any non-numeric characters in Plaid identifiers, as they are case sensitive.

##### Account churn 

If the underlying account has not been closed or changed at the bank and the `account_id` no longer appears, Plaid may have removed the account entirely or assigned the account a new `account_id`, a situation known as "account churn".

Some common causes for account churn are:

*   The Item was in an unhealthy state for an extended period of time. If an Item has remained in an error state for over a year, its underlying data may be removed. If the Item is then later refreshed, the Item data will be re-generated, resulting in new `account_id` data.
*   The bank or user drastically changing the name of the account, e.g. an account named "Savings account" becomes "Jane's vacation fund".
*   The account's mask is changed by the bank, which can occur when banks change their backend systems.

Account churn caused by the latter two reasons is unexpected API behavior. If you experience account churn on an Item that was otherwise healthy, [file a Support ticket](https://dashboard.plaid.com/support/new/financial-institutions/missing-data/missing-accounts) .

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_ACCOUNT_ID",
 "error_message": "failed to find requested account ID for requested item",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_API\_KEYS 

##### The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard. 

##### Common causes 

*   The API keys are not valid for the environment being used, which can commonly happen when switching between development environments and forgetting to switch API keys

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_API_KEYS",
 "error_message": "invalid client_id or secret provided",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_AUDIT\_COPY\_TOKEN 

##### The audit copy token supplied to the server was invalid. 

##### Common causes 

*   You attempted to access an Asset Report using an `audit_copy_token` that is invalid or was revoked using [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) or [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) .

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_AUDIT_COPY_TOKEN",
 "error_message": null,
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_INSTITUTION 

##### The institution\_id specified is invalid or does not exist. 

##### Common causes 

*   The `institution_id` specified is invalid or does not exist.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_INSTITUTION",
 "error_message": "invalid institution_id provided",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_LINK\_CUSTOMIZATION 

##### The Link customization is not valid for the request. 

##### Common causes 

*   The Link customization is missing a use case and the session is enabled for Data Transparency Messaging.
*   This error can happen when requesting to update account selections with a Link customization that does not enable [Account Select v2](https://plaid.com/docs/link/customization/index.html.md#account-select) .

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_LINK_CUSTOMIZATION",
 "error_message": "requested link customization is not set to update account selection",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_LINK\_TOKEN 

##### The link\_token provided to initialize Link was invalid. 

##### Sample user-facing error message 

Username or password incorrect: Check that your credentials are the same that you use for this institution

##### Common causes 

*   The `link_token` has expired. A `link_token` lasts at least 30 minutes before expiring.
*   The `link_token` was already used. A `link_token` can only be used once, except when working in the Sandbox test environment.
*   The `link_token` was created in a different environment than the one it was used with. For example, a Sandbox `link_token` was used in Production.
*   A user entered invalid credentials too many times during the Link flow, invalidating the `link_token`.

##### Troubleshooting steps 

For more detailed instructions on handling this error, see [Handling invalid Link Tokens](https://plaid.com/docs/link/handle-invalid-link-token/index.html.md) .

API error responseLink error preview

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_LINK_TOKEN",
 "error_message": "invalid link_token provided",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_PROCESSOR\_TOKEN 

##### The processor\_token provided to initialize Link was invalid. 

##### Common causes 

*   The `processor_token` used to initialize Link was invalid.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_PROCESSOR_TOKEN",
 "error_message": null,
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_PRODUCT 

##### Your client ID does not have access to this product. 

##### Common causes 

*   The endpoint you are trying to access is not enabled for your account in the environment where you are trying to use it. For example, Identity Verification access is only available in Sandbox after you have received Production access.
*   Your integration is using a partner endpoint integration that has not yet been enabled in the Dashboard.
*   Your integration is attempting to call a processor endpoint on an Item that was initialized with products that are not compatible with processor endpoints.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_PRODUCT",
 "error_message": "client is not authorized to access the following products: [\"identity_verification\"]",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ADDITIONAL\_CONSENT\_REQUIRED 

##### The end user has not provided consent to the requested product 

##### Common causes 

*   You are using a Link flow that is enabled for [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) and are trying to access an endpoint you did not collect consent for.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "ADDITIONAL_CONSENT_REQUIRED",
 "error_message": "client does not have user consent to access the PRODUCT_AUTH product",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_PUBLIC\_TOKEN 

##### Common causes 

*   Public tokens are in the format: `public-<environment>-<identifier>`
*   This error can happen when the `public_token` you provided is invalid, pertains to a different API environment, or has expired.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_PUBLIC_TOKEN",
 "error_message": "could not find matching public token",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_STRIPE\_ACCOUNT 

##### The supplied Stripe account is invalid 

##### Common causes 

After [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) was called, Plaid received a response from Stripe indicating that the Stripe account specified in the API call's `account_id` is invalid.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_STRIPE_ACCOUNT",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_USER\_TOKEN 

##### The supplied user token is invalid 

##### Common causes 

*   The user token is not associated with the given user ID.
*   The user token is invalid or pertains to a different API environment.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_USER_TOKEN",
 "error_message": "could not find matching user token",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_WEBHOOK\_VERIFICATION\_KEY\_ID 

##### The key\_id provided to the webhook verification endpoint was invalid. 

##### Common causes 

*   A request was made to [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) using an invalid `key_id`.
*   The call to [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) was made from an environment different than the one the webhook was sent from (for example, verification of a Sandbox webhook was attempted against Production).

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "INVALID_WEBHOOK_VERIFICATION_KEY_ID",
 "error_message": "invalid key_id provided. note that key_ids are specific to Plaid environments, and verification requests must be made to the same environment that the webhook was sent from",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TOO\_MANY\_VERIFICATION\_ATTEMPTS 

##### The user attempted to verify their Manual Same-Day micro-deposit codes more than 3 times and their Item is now permanently locked. The user must retry submitting their account information in Link. 

##### Sample user-facing error message 

No attempts remaining: You’ve used up all of your attempts. To continue, connect a different bank

##### Common causes 

*   Your user repeatedly submitted incorrect micro-deposit codes when verifying an account via Manual Same-Day micro-deposits.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "TOO_MANY_VERIFICATION_ATTEMPTS",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### UNAUTHORIZED\_ENVIRONMENT 

##### Your client ID does not have access to this API environment. See which environments you are enabled for from the Dashboard. 

##### Sample user-facing error message 

Unauthorized environment: Your Client ID is not authorized to access this API environment. Contact Support to gain access

##### Common causes 

*   You may not be enabled for the environment you are using.
*   Your code may be calling a deprecated endpoint.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "UNAUTHORIZED_ENVIRONMENT",
 "error_message": "you are not authorized to create items in this api environment. Go to the Dashboard (https://dashboard.plaid.com) to see which environments you are authorized for.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### UNAUTHORIZED\_ROUTE\_ACCESS 

##### Your client ID does not have access to this route. 

##### Common causes 

*   The endpoint you are trying to access must be manually enabled for your account.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "UNAUTHORIZED_ROUTE_ACCESS",
 "error_message": "you are not authorized to access this route in this api environment.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### USER\_PERMISSION\_REVOKED 

##### The end user has revoked access to their data. 

##### Common causes 

*   The end user revoked access to their data via the Plaid consumer portal at my.plaid.com.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_INPUT",
 "error_code": "USER_PERMISSION_REVOKED",
 "error_message": "the holder of this account has revoked their permission for your application to access it",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Invalid Request errors | Plaid Docs

Invalid Request Errors 
=======================

#### Guide to troubleshooting invalid request errors 

#### INCOMPATIBLE\_API\_VERSION 

##### The request uses fields that are not compatible with the API version being used. 

##### Common causes 

*   The API endpoint was called using a `public_key` for authentication rather than a `client_id` and `secret`.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INCOMPATIBLE_API_VERSION",
 "error_message": "The public_key cannot be used for this endpoint as of version {version-date} of the API. Please use the client_id and secret instead.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_ACCOUNT\_NUMBER 

##### The provided account number was invalid. 

##### Sample user-facing error message 

Account or routing number incorrect: Check with your bank and make sure that your account and routing numbers are entered correctly

##### Alternative user-facing error message 

_This account does not support ACH debit. Please retry with a different account._

##### Common causes 

*   While in the Instant Match, Automated Micro-deposit, or Same-Day Micro-deposit Link flows, the user provided an account number whose last four digits did not match the account mask of their bank account.
*   If the user entered the correct account number, Plaid may have been unable to retrieve an account mask.
*   If the user entered the correct account number, the account may be a non-debitable account or a non-supported account type. Common examples of non-debitable depository accounts include savings accounts at Chime or at Navy Federal Credit Union (NFCU).

##### Troubleshooting steps 

If the account number was correct and the account was a debitable supported type, please [contact Plaid Support](https://dashboard.plaid.com/support/new/) .

API error responseLink error preview

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_ACCOUNT_NUMBER",
 "error_message": "The provided account number was invalid.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_BODY 

##### The request body was invalid. 

##### Common causes 

*   The JSON request body was malformed.
*   The request `content-type` was not of type `application/json`. The Plaid API only accepts JSON text as the MIME media type, with `UTF-8` encoding, conforming to [RFC 4627](http://www.ietf.org/rfc/rfc4627.txt) .

```json
content-type: 'application/json'
```

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_BODY",
 "error_message": "body could not be parsed as JSON",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_CONFIGURATION 

##### /link/token/create was called with invalid configuration settings 

##### Common causes 

*   One or more of the configuration objects provided to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) does not match the request schema for that endpoint.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_CONFIGURATION",
 "error_message": "please ensure that the request body is formatted correctly",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_FIELD 

##### One or more of the request body fields were improperly formatted or invalid. 

##### Common causes 

*   One or more fields in the request body were invalid, malformed, or used a wrong type. The `error_message` field will specify the erroneous field and how to resolve the error.
*   Personally identifiable information (PII), such as an email address or phone number, was provided for a field where PII is not allowed, such as `user.client_user_id`.
*   An unsupported country code was used in Production. Consult the [API Reference](https://plaid.com/docs/api/index.html.md) for the endpoint being used for a list of valid country codes.
*   An request parameter that is optional in the API schema was not provided in a context where it is required. For example, [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) was called without specifying `options.min_last_updated_datetime` on a Capital One (`ins_128026`) Item with non-depository accounts.
*   The value used in the field is not valid for business logic reasons. For example, [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) or [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) endpoints were called with a `client_transaction_id` for which [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) was never called, or [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) was called using an `authorization_id` whose `decision` value is `declined`.
*   A request to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) was sent specifying an OAuth redirect URI that was not added to the [allowed redirect URIs](https://dashboard.plaid.com/developers/api) list in the Dashboard.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_FIELD",
 "error_message": "{{ error message is specific to the given / missing request field }}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_HEADERS 

##### The request was missing a required header. 

##### Common causes 

*   The request was missing a `header`, typically the `Content-Type` header.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_HEADERS",
 "error_message": "{{ error message is specific to the given / missing header }}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### MISSING\_FIELDS 

##### The request was missing one or more required fields. 

##### Common causes 

*   The request body is missing one or more required fields. The `error_message` field will list the missing field(s).

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "MISSING_FIELDS",
 "error_message": "the following required fields are missing: {fields}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_LONGER\_AVAILABLE 

##### The endpoint requested is not available in the API version being used. 

##### Common causes 

*   The endpoint you requested has been discontinued and no longer exists in the Plaid API.

##### Troubleshooting steps 

```json
http code 404
{
 "error_type": "INVALID_REQUEST",
 "error_code": "NO_LONGER_AVAILABLE",
 "error_message": "This endpoint has been discontinued as of version {version-date} of the API.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NOT\_FOUND 

##### The endpoint requested does not exist. 

##### Common causes 

*   The endpoint you requested does not exist in the Plaid API.

##### Troubleshooting steps 

```json
http code 404
{
 "error_type": "INVALID_REQUEST",
 "error_code": "NOT_FOUND",
 "error_message": "not found",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### SANDBOX\_ONLY 

##### The requested endpoint is only available in Sandbox. 

##### Common causes 

*   The requested endpoint is only available in the [Sandbox API Environment](https://plaid.com/docs/sandbox/index.html.md) .

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "SANDBOX_ONLY",
 "error_message": "access to {api/route} is only available in the sandbox environment at https://sandbox.plaid.com/",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### UNKNOWN\_FIELDS 

##### The request included a field that is not recognized by the endpoint. 

##### Common causes 

*   The request body included one or more extraneous fields. The `error_message` field will list the unrecognized field(s).

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_REQUEST",
 "error_code": "UNKNOWN_FIELDS",
 "error_message": "the following fields are not recognized by this endpoint: {fields}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Invalid Result errors | Plaid Docs

Invalid Result errors 
======================

#### Guide to troubleshooting invalid result errors 

#### LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE 

##### No data is available from the Item within the specified date-time. 

##### Common causes 

*   [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) was called with a parameter specifying the minimum acceptable data freshness, but no balance data meeting those requirements was available from the institution.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_RESULT",
 "error_code": "LAST_UPDATED_DATETIME_OUT_OF_RANGE",
 "error_message": "requested datetime out of range, most recently updated balance 2021-01-01T00:00:00Z",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PLAID\_DIRECT\_ITEM\_IMPORT\_RETURNED\_INVALID\_MFA 

##### The Plaid Direct Item import resulted in invalid MFA. 

##### Common causes 

*   No known causes.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "INVALID_RESULT",
 "error_code": "PLAID_DIRECT_ITEM_IMPORT_RETURNED_INVALID_MFA",
 "error_message": "Plaid Direct Item Imports should not result in MFA.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Item errors | Plaid Docs

Item Errors 
============

#### Guide to troubleshooting Item errors 

#### ACCESS\_NOT\_GRANTED 

##### The user did not grant necessary permissions for their account. 

##### Sample user-facing error message 

Insufficient Sharing Permissions: There was an error connecting to your account. Try linking your account again by selecting the required information to share with this application.

##### Common causes 

*   This Item's access is affected by institution-hosted access controls.
*   The user did not agree to share, or has revoked, access to the data required for the requested product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account.
*   The user does not have permission to share required information about the account. This can happen at some institutions using OAuth connections if the user is not the account owner (for example, they have a role such as trustee, investment advisor, power of attorney holder, or authorized cardholder).

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "ACCESS_NOT_GRANTED",
 "error_message": "access to this product was not granted for the account",
 "display_message": "The user did not grant the necessary permissions for this product on their account.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTANT\_MATCH\_FAILED 

##### Instant Match could not be initialized for the Item. 

##### Common causes 

*   Instant Auth could not be used for the Item, and Instant Match has been enabled for your account, but a country other than `US` is specified in Link's country code initialization.
*   The Item does not support Instant Auth or Instant Match. If this is the case, Plaid will automatically attempt to enter a micro-deposit based verification flow.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INSTANT_MATCH_FAILED",
 "error_message": "Item cannot be verified through Instant Match. Ensure you are correctly enabling all auth features in Link.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSUFFICIENT\_CREDENTIALS 

##### The user did not provide sufficient authorization in order to link their account via an OAuth login flow. 

##### Sample user-facing error message 

Couldn't connect to Platypus Bank: Please try to sign in again, or connect another institution.

##### Common causes 

*   Your user abandoned the bank OAuth flow without completing it.

##### Troubleshooting steps 

If this error persists, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INSUFFICIENT_CREDENTIALS",
 "error_message": "insufficient authorization was provided to complete the request",
 "display_message": "INSUFFICIENT_CREDENTIALS",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_CREDENTIALS 

##### The financial institution indicated that the credentials provided were invalid. 

##### Sample user-facing error message 

The credentials you provided were incorrect: Check that your credentials are the same that you use for this institution

##### Link user experience 

Your user will be redirected to the `Credentials` pane to retry entering correct credentials.

##### Common causes 

*   The user entered incorrect credentials at their selected institution.
    *   Extra spaces, capitalization, and punctuation errors are common causes of `INVALID_CREDENTIALS`.
*   The institution requires special configuration steps before the user can link their account with Plaid. KeyBank, Interactive Brokers, and Betterment are examples of institutions that require this setup.
*   The user selected the wrong institution.
    *   Plaid supports institutions that have multiple login portals for the various products they offer, and it is common for users to confuse a different selection for the one which their credentials would actually be accepted.
    *   This confusion is particularly common between Vanguard (brokerage accounts) and My Vanguard Plan (retirement accounts). This is also common for users attempting to link prepaid stored-value cards, as many institutions have separate login portals specifically for those cards.

##### Troubleshooting steps 

Note: The Institution may lock a user out of their account after 3-5 repeated attempts, resulting in an [ITEM\_LOCKED](https://plaid.com/docs/errors/item/index.html.md#item_locked) error.

If the credentials are confirmed to be legitimate, and a user still cannot authenticate, please submit an 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INVALID_CREDENTIALS",
 "error_message": "the provided credentials were not correct",
 "display_message": "The provided credentials were not correct. Please try again.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_MFA 

##### The institution indicated that the provided response for MFA was invalid 

##### Sample user-facing error message 

The credentials you provided were incorrect: For security reasons, your account may be locked after several unsuccessful attempts

##### Link user experience 

Your user will be redirected to the MFA pane to retry entering the correct value.

##### Common causes 

*   The user entered an incorrect answer for the security question presented by the selected institution.
*   The user selected an MFA device that is not active.
*   The institution failed to send the one-time code for the user's selected device.

##### Troubleshooting steps 

If the user still cannot log in despite providing correct information, or if they cannot receive an MFA token despite having the correct device, please submit a 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INVALID_MFA",
 "error_message": "the provided MFA response(s) were not correct",
 "display_message": "The provided MFA responses were not correct. Please try again.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_SEND\_METHOD 

##### Returned when the method used to send MFA credentials was deemed invalid by the institution. 

##### Link user experience 

Your user will be shown an error message indicating that an internal error occurred and will be prompted to close Link.

##### Common causes 

*   The institution is experiencing login issues.
*   The integration between Plaid and the financial institution is experiencing errors.

##### Troubleshooting steps 

If the error persists, submit a 'Multi-factor authentication issues' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/mfa-issue) ticket with the following identifiers: `institution_id` and either `link_session_id` or `request_id`.

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INVALID_SEND_METHOD",
 "error_message": "the provided MFA send_method was invalid",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_PHONE\_NUMBER 

##### The submitted phone number was invalid. 

##### Sample user-facing error message 

Invalid Phone Number: We couldn't verify that 4151231234 is a valid number. Please re-enter your phone number to try again.

##### Link user experience 

Your user will be redirected to the phone number input pane to retry submitting a valid phone number.

##### Common causes 

*   The user entered an invalid phone number. Only US and CA phone numbers are accepted for the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) .

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INVALID_PHONE_NUMBER",
 "error_message": "the provided phone number was invalid",
 "display_message": "The provided phone number was invalid. Please try again.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_OTP 

##### The submitted OTP was invalid. 

##### Sample user-facing error message 

Security code incorrect: Check that the code you entered is the same code that was sent to you

##### Link user experience 

Your user will be redirected to the OTP input pane to retry submitting a valid OTP.

##### Common causes 

*   The user entered an invalid OTP.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INVALID_OTP",
 "error_message": "the provided OTP was invalid",
 "display_message": "The provided OTP was invalid. Please try again.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_UPDATED\_USERNAME 

##### The username entered during update mode did not match the original username. 

##### Sample user-facing error message 

Error: Try entering your bank account username again. If you recently changed it, you may need to un-link your account and then re-link.

##### Link user experience 

Your user will be directed to enter a different username.

##### Common causes 

*   While linking an account in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) , the user provided a username that doesn't match the original username provided when they originally linked the account.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "INVALID_UPDATED_USERNAME",
 "error_message": "the username provided to /item/credentials/update does not match the original username for the item",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ITEM\_CONCURRENTLY\_DELETED 

##### This item was deleted while the operation was in progress. 

##### Common causes 

*   An Item was deleted via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) while a request for its data was in process.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "ITEM_CONCURRENTLY_DELETED",
 "error_message": "This item was deleted while the operation was in progress",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ITEM\_LOCKED 

##### The financial institution indicated that the user's account is locked. The user will need to work with the institution directly to unlock their account. 

##### Sample user-facing error message 

Too many attempts: Your account is locked for security reasons. Reset your bank username and password, and then try again.

##### Link user experience 

Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account.

##### Common causes 

*   The user entered their credentials incorrectly after more than 3-5 attempts, triggering the institution’s fraud protection systems and locking the user’s account.

##### Troubleshooting steps 

If the user is persistently locked out of their institution, submit an 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "ITEM_LOCKED",
 "error_message": "the account is locked. prompt the user to visit the institution's site and unlock their account",
 "display_message": "The given account has been locked by the financial institution. Please visit your financial institution's website to unlock your account.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ITEM\_LOGIN\_REQUIRED 

##### The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode. 

##### Sample user-facing error message 

Username or password incorrect: If you've recently updated your account with this institution, be sure you're entering your updated credentials

##### Common causes 

*   The institution does not use an OAuth-based connection and the user changed their password.
*   The institution does not use an OAuth-based connection and the user changed their multi-factor settings, or their multi-factor authentication has expired.
*   The institution has undergone a migration from a non-OAuth-based connection to an OAuth-based connection.
*   The institution uses an OAuth-based connection and the user's access-consent is no longer valid, either because it has expired, or because the user revoked access.
*   The institution uses an OAuth-based connection that does not allow duplicate Items, but the user connected a duplicate Item to the same application.
*   (Sandbox only) The Item was created in the Sandbox environment and is over 30 days old.

##### Troubleshooting steps 

If the error is legitimate, having the user authenticate again should generally return their Item to a healthy state without further intervention.

If this error persists, please submit a [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "ITEM_LOGIN_REQUIRED",
 "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ITEM\_NOT\_FOUND 

##### The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user 

##### Common causes 

*   Item was previously removed via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) .
*   The user has depermissioned or deleted their Item via [my.plaid.com](https://my.plaid.com) .
*   Plaid support has deleted the Item in response to a data deletion request from the user.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "ITEM_NOT_FOUND",
 "error_message": "The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ITEM\_NOT\_SUPPORTED 

##### Plaid is unable to support this user's accounts due to restrictions in place at the financial institution. 

##### Sample user-facing error message 

Account not currently supported: Your account is not currently supported. Please log in using a different account

##### Link user experience 

Your user will be redirected to the Institution Select pane to connect a different account.

##### Common causes 

*   Plaid does not currently support the types of accounts for the the connected Item, due to restrictions in place at the selected institution.
*   Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution.
*   The credentials provided are for a 'guest' account or other account type with limited account access.
*   A processor partner token is being created or used, but the country, products, or account types associated with the Item are not supported by the processor partner.

##### Troubleshooting steps 

If the error persists and none of the common causes above seem to apply, [contact Support](https://dashboard.plaid.com/support/new/) .

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "ITEM_NOT_SUPPORTED",
 "error_message": "this account is currently not supported",
 "display_message": "The given account is not currently supported for this financial institution. We apologize for the inconvenience.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### MFA\_NOT\_SUPPORTED 

##### Returned when the user requires a form of MFA that Plaid does not support for a given financial institution. 

##### Sample user-facing error message 

Your account settings are incompatible: Your account could not be connected because the multi-factor authentication method it uses is not currently supported. Please try a different account.

##### Link user experience 

Your user will be redirected to the Institution Select pane to connect a different account.

##### Common causes 

*   Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution.
*   The user's multi-factor authentication setting is configured not to remember trusted devices and instead to present a multi-factor challenge on every login attempt. This prevents Plaid from refreshing data asynchronously, which many products (especially Transactions) require.

##### Troubleshooting steps 

If user's settings are not configured to present a multi-factor challenge on every login attempt but this error is still appearing, submit a 'Multi-factor authentication issues' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/mfa-issue) ticket with the following identifiers: `institution_id` and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "MFA_NOT_SUPPORTED",
 "error_message": "this account requires a MFA type that we do not currently support for the institution",
 "display_message": "The multi-factor security features enabled on this account are not currently supported for this financial institution. We apologize for the inconvenience.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_ACCOUNTS 

##### Returned when there are no open accounts associated with the Item. 

##### Sample user-facing error message 

No compatible accounts: Your credentials are correct, but we couldn’t find any accounts with this institution that are compatible with this application. Try another account, financial institution, or check for another connection method.

##### Link user experience 

Your user will be redirected to the Institution Select pane to connect a different account.

##### Common causes 

*   The user successfully logged into their account, but Plaid was unable to retrieve any open, active, or eligible accounts in the connected Item.
*   The user closed their account.
*   The user revoked access to the account.
*   The account experienced [account churn](https://plaid.com/docs/errors/invalid-input/index.html.md#account-churn) , which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked.
*   There is a problem with Plaid's connection to the user's financial institution.

##### Troubleshooting steps 

If this error persists and the user does have accounts at the institution that you should be able to access, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "NO_ACCOUNTS",
 "error_message": "no valid accounts were found for this item",
 "display_message": "No valid accounts were found at the financial institution. Please visit your financial institution's website to confirm accounts are available.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_AUTH\_ACCOUNTS or no-depository-accounts 

##### Returned from POST /auth/get when there are no valid accounts for which account and routing numbers could be retrieved. 

##### Sample user-facing error message 

No eligible accounts: We didn't find any checking or savings accounts at this institution. Please try linking another institution

##### Common causes 

*   [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) was called on an Item with no accounts that can support Auth, or accounts that do support Auth were filtered out. Only debitable checking, savings, and cash management accounts can be used with Auth.
*   Plaid's ability to retrieve Auth data from the institution has been temporarily disrupted.
*   The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any compatible accounts. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share account and routing number information even if they have already opted in to sharing information about their checking or savings account.
*   The end user revoked access to the account.
*   The account experienced [account churn](https://plaid.com/docs/errors/invalid-input/index.html.md#account-churn) , which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked.

##### Troubleshooting steps 

If the problem persists even though the end user has confirmed that they have a debitable checking, savings, or cash management account at the institution, [open a support ticket](https://dashboard.plaid.com/support/new) .

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "NO_AUTH_ACCOUNTS",
 "error_message": "There are no valid checking or savings account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_INVESTMENT\_ACCOUNTS 

##### Returned from POST /investments/holdings/get, POST /investments/transactions/get, or Link initialized with the Investments product, when there are no valid investment account(s) for which holdings or transactions could be retrieved. 

##### Sample user-facing error message 

No investment accounts: None of your accounts are investment accounts. Please connect using a different bank

##### Common causes 

*   Link was initialized with the Investments product, but the user attempted to link an account with no investment accounts.
*   The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint was called, but there are no investment accounts associated with the Item.
*   The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts.

##### Troubleshooting steps 

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, [open a support ticket](https://dashboard.plaid.com/support/new) .

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "NO_INVESTMENT_ACCOUNTS",
 "error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_INVESTMENT\_AUTH\_ACCOUNTS 

##### Returned from POST /investments/holdings/get or POST /investments/transactions/get when there are no valid investment account(s) for which holdings or transactions could be retrieved. 

##### Common causes 

*   The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint was called, but there are no investment accounts associated with the Item.
*   The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts.

##### Troubleshooting steps 

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, [open a support ticket](https://dashboard.plaid.com/support/new) .

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "NO_INVESTMENT_AUTH_ACCOUNTS",
 "error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NO\_LIABILITY\_ACCOUNTS 

##### Returned from POST /liabilities/get when there are no valid liability account(s) for which liabilities could be retrieved. 

##### Sample user-facing error message 

No liability accounts: None of your accounts are liability accounts. Please connect using a different bank

##### Common causes 

*   The [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) endpoint was called, but there are no supported liability accounts associated with the Item.
*   The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any liabilities accounts.

##### Troubleshooting steps 

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, [open a support ticket](https://dashboard.plaid.com/support/new) .

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "NO_LIABILITY_ACCOUNTS",
 "error_message": "There are no valid liability account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PASSWORD\_RESET\_REQUIRED 

##### The user must log in directly to the financial institution and reset their password. 

##### Common causes 

*   The institution is blocking access because the user needs to reset their password.

##### Troubleshooting steps 

Ask that the user log in to the bank, and confirm whether they are presented with a message to reset their password. If they are, they should follow the instructions to reset their password. Once the password is reset, they should attempt to link their account again.

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "PASSWORD_RESET_REQUIRED",
 "error_message": "user must reset their password",
 "display_message": "The user needs to reset their password for their account",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCT\_NOT\_ENABLED 

##### A requested product was not enabled for the current access token. Please ensure it is included when when initializing Link and create the Item again. 

##### Common causes 

*   You requested a product that was not enabled for the current access token. Ensure it is included when when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and create the Item again.

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "PRODUCT_NOT_ENABLED",
 "error_message": "A requested product was not enabled for the current access token. Please ensure it is included when when initializing Link and create the Item again.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCT\_NOT\_READY 

##### Returned when a data request has been made for a product that is not yet ready. 

For the Assets version of this error, see [ASSET\_REPORT\_ERROR: PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/assets/index.html.md#product_not_ready) . For the Income Verification version, see [INCOME\_VERIFICATION\_ERROR: PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/income/index.html.md#product_not_ready) .

##### Common causes 

*   [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) was called before the first 30 days of transactions data could be extracted. This typically happens if the endpoint was called within a few seconds of linking the Item. It will also happen if [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) was called for the first time on an Item that was not initialized with `transactions` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. Note that this error does not occur when using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) ; if called too early, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) will simply fail to return any transactions.
*   Occasionally, this error can occur upon calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) if Plaid's attempt to extract transactions for the Item has failed, due to a connectivity error with the financial institution, and Plaid has never successfully extracted transactions for the Item in the past. If this happens, Plaid will continue to retry the extraction at least once a day.
*   [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) was called for the first time on a new Item before any balance data could be extracted for the Item. When called, [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will return a `PRODUCT_NOT_READY` error if cached balance data does not exist and new balance data could not be obtained after 15 seconds. For some customers who participated in the early phases of the Signal beta, [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will return `PRODUCT_NOT_READY` immediately if cached balance data is not available when [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is called.
*   [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) was called on an Item that hasn't been verified, which is possible when using [micro-deposit based verification](https://plaid.com/docs/auth/coverage/index.html.md) .
*   [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) was called before the investments data could be extracted. This typically happens when the endpoint is called with the option for `async_update` set to true, and called again within a few seconds of linking the Item. It will also happen if [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) (with `async_update` set to true) was called for the first time on an Item that was not initialized with `investments` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "PRODUCT_NOT_READY",
 "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PRODUCTS\_NOT\_SUPPORTED 

##### Returned when a data request has been made for an Item for a product that it does not support. Use the /item/get endpoint to find out which products an Item supports. 

##### Common causes 

*   A product endpoint request was made for an Item that does not support that product. This can happen when trying to call a product endpoint on an Item if the product was not included in either the `products` or `optional_products` arrays when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   Updated accounts have been requested for an Item initialized with the Assets product, which does not support adding or updating accounts after the initial Link.
*   You are attempting to call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) on a non-US financial institution.
*   You are attempting to call [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) on a manually linked item (Database Insights, Database Match, Instant Micro-deposits, Same Day Micro-deposits).
*   You are attempting to call [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) on a Capital One Item that contains only credit cards or other non-depository products. Capital One does not support the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint for non-depository products.
*   You are attempting to call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) on an Item that was manually linked (using Database Insights, Database Match, Instant Micro-deposits, or Same Day Micro-deposits) that has not been seen on the Plaid network before.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "PRODUCTS_NOT_SUPPORTED",
 "error_message": "",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### USER\_SETUP\_REQUIRED 

##### The user must log in directly to the financial institution and take some action before Plaid can access their accounts. 

##### Sample user-facing error message 

Action required with your account: Log in to your bank and update your account. Then, return to Plaid to continue.

##### Link user experience 

Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account.

##### Common causes 

*   The institution requires special configuration steps before the user can link their account with Plaid. KeyBank and Betterment are two examples of institutions that require this setup.
*   The user’s account is not fully set up at their institution.
*   The institution is blocking access due to an administrative task that requires completion. This error can arise for a number of reasons, the most common being:
    *   The user must agree to updated terms and conditions.
    *   The user must reset their password.
    *   The user must enter additional account information.

##### Troubleshooting steps 

Ask that the user log in to the bank, and confirm whether they are presented with some form of agreement page, modal, or some other actionable task. The user should also check their bank website for special settings to allow access for third-party apps, such as a "third party application password" or "allow third party access" setting.

This can usually be done completely online, but there are some financial institutions that require the user to call a phone number, or access a physical branch.

If the user is still unable to log in to their institution, please submit a 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "USER_SETUP_REQUIRED",
 "error_message": "the account has not been fully set up. prompt the user to visit the issuing institution's site and finish the setup process",
 "display_message": "The given account is not fully setup. Please visit your financial institution's website to setup your account.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### USER\_INPUT\_TIMEOUT 

##### The user did not complete a step in the Link flow, and it timed out. 

##### Sample user-facing error message 

Session expired: Please re-enter your information to link your accounts.

##### Common causes 

*   Your user did not complete the account selection flow within five minutes.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "ITEM_ERROR",
 "error_code": "USER_INPUT_TIMEOUT",
 "error_message": "user must retry this operation",
 "display_message": "The application timed out waiting for user input",
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Microdeposits errors | Plaid Docs

Micro-deposits Errors 
======================

#### Guide to troubleshooting micro-deposits errors 

#### BANK\_TRANSFER\_ACCOUNT\_BLOCKED 

##### The bank transfer could not be completed because a previous transfer involving the same end-user account resulted in an error. 

##### Common causes 

*   Plaid cannot send micro-deposits to verify this account because it has flagged the account as not valid for use. This may happen, for example, because a previous attempt by Plaid to transfer funds to this end user account resulted in an "account frozen" or "invalid account number" error.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "BANK_TRANSFER_ERROR",
 "error_code": "BANK_TRANSFER_ACCOUNT_BLOCKED",
 "error_message": "bank transfer was blocked due to a previous ACH return on this account",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - OAuth errors | Plaid Docs

OAuth Errors 
=============

#### Guide to troubleshooting OAuth errors 

For information on troubleshooting OAuth errors in Link not related to a specific error code, see [Link troubleshooting: OAuth not working](https://plaid.com/docs/link/troubleshooting/index.html.md#oauth-not-working) .

#### INCORRECT\_OAUTH\_NONCE 

##### An incorrect OAuth nonce was supplied when re-initializing Link. 

##### Common causes 

*   During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if a different nonce is supplied during the re-initialization process than was originally supplied to Link for the first initialization step.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "OAUTH_ERROR",
 "error_code": "INCORRECT_OAUTH_NONCE",
 "error_message": "nonce does not match",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INCORRECT\_LINK\_TOKEN 

##### An incorrect Link token was supplied when re-initializing Link. 

##### Common causes 

*   During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if a different `link_token` is supplied during the re-initialization process than was originally supplied to Link for the first initialization step.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "OAUTH_ERROR",
 "error_code": "INCORRECT_LINK_TOKEN",
 "error_message": "link token does not match original link token",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### OAUTH\_STATE\_ID\_ALREADY\_PROCESSED 

##### The OAuth state has already been processed. 

##### Common causes 

*   During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if the OAuth state ID used during re-initialization of Link has already been used.

##### Troubleshooting steps 

```json
http code 208
{
 "error_type": "OAUTH_ERROR",
 "error_code": "OAUTH_STATE_ID_ALREADY_PROCESSED",
 "error_message": null,
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### OAUTH\_STATE\_ID\_NOT\_FOUND 

##### The OAuth state id could not be found. 

##### Common causes 

*   An internal Plaid error occurred.

##### Troubleshooting steps 

```json
http code 404
{
 "error_type": "OAUTH_ERROR",
 "error_code": "OAUTH_STATE_ID_NOT_FOUND",
 "error_message": "the provided oauth_state_id wasn't found",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Partner errors | Plaid Docs

Partner Errors 
===============

#### Guide to troubleshooting partner errors 

#### CUSTOMER\_NOT\_FOUND 

##### Customer not found 

##### Common causes 

*   The end customer could not be found.

##### Troubleshooting steps 

```json
http code 404
{
 "error_type": "PARTNER_ERROR",
 "error_code": "CUSTOMER_NOT_FOUND",
 "error_message": "the customer was not found",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### FLOWDOWN\_NOT\_COMPLETE 

##### Flowdown not complete 

##### Common causes 

*   A flowdown, which is a prerequisite for creating an end customer, has not been completed.

##### Troubleshooting steps 

```json
http code 412
{
 "error_type": "PARTNER_ERROR",
 "error_code": "FLOWDOWN_NOT_COMPLETE",
 "error_message": "you must complete a flowdown to create and enable customers",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### QUESTIONNAIRE\_NOT\_COMPLETE 

##### Questionnaire not complete 

##### Common causes 

*   A security questionnaire, which is a prerequisite for creating an end customer, has not been submitted.

##### Troubleshooting steps 

```json
http code 412
{
 "error_type": "PARTNER_ERROR",
 "error_code": "QUESTIONNAIRE_NOT_COMPLETE",
 "error_message": "you must complete the security questionnaire to create and enable customers",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### CUSTOMER\_NOT\_READY\_FOR\_ENABLEMENT 

##### Customer not ready for enablement 

##### Common causes 

*   The end customer requires manual approval from Plaid's Partnerships team.
*   The end customer has been denied access to the Plaid API.

##### Troubleshooting steps 

```json
http code 412
{
 "error_type": "PARTNER_ERROR",
 "error_code": "CUSTOMER_NOT_READY_FOR_ENABLEMENT",
 "error_message": "this customer is not ready for enablement",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### CUSTOMER\_ALREADY\_ENABLED 

##### Customer already enabled 

##### Common causes 

*   The end customer has already been enabled.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "CUSTOMER_ALREADY_ENABLED",
 "error_message": "this customer has already been enabled",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### CUSTOMER\_ALREADY\_CREATED 

##### Customer already created 

##### Common causes 

*   The end customer has already been created.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "CUSTOMER_ALREADY_CREATED",
 "error_message": "this customer has already been created",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### LOGO\_REQUIRED 

##### Logo required 

##### Common causes 

*   A logo is required for this customer because the `create_link_customization` field was set to `true` and the co-branded consent field is in use.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "LOGO_REQUIRED",
 "error_message": "a logo is required because create_link_customization is set to true and the co-branded consent pane is in use",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVALID\_LOGO 

##### Invalid logo 

##### Common causes 

*   The logo is not a valid base64-encoded string of a PNG of size 1024x1024.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "INVALID_LOGO",
 "error_message": "the logo must be a base64-encoded string of a PNG of size 1024x1024",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### CONTACT\_REQUIRED 

##### Contact required 

##### Common causes 

*   A billing or technical contact is required, either in the API request or in the Dashboard.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "CONTACT_REQUIRED",
 "error_message": "billing or technical contacts must be submitted either in the request or filled in for your team in the dashboard",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ASSETS\_UNDER\_MANAGEMENT\_REQUIRED 

##### Assets Under Management required 

##### Common causes 

*   The `assets_under_management` field is required because you have a monthly service commitment, but it was omitted from your API request.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "ASSETS_UNDER_MANAGEMENT_REQUIRED",
 "error_message": "assets under management must be submitted because your team has a monthly service commitment",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### CUSTOMER\_REMOVAL\_NOT\_ALLOWED 

##### Removal not allowed 

##### Common causes 

*   You have attempted to remove an end customer that has already been enabled in the Production environment, which is not allowed.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PARTNER_ERROR",
 "error_code": "CUSTOMER_REMOVAL_NOT_ALLOWED",
 "error_message": "removal of a production-enabled end customer is not allowed. talk to your account manager to remove this end customer.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Payment errors (Europe) | Plaid Docs

Payment Errors 
===============

#### Errors specific to the Payment Initiation product 

#### PAYMENT\_BLOCKED 

##### The payment was blocked for violating compliance rules. 

##### Common causes 

*   The payment amount value when calling [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) was too high.
*   Too many payments were created in a short period of time.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_BLOCKED",
 "error_message": "payment blocked",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_CANCELLED 

##### The payment was cancelled. 

##### Sample user-facing error message 

Payment cancelled: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The payment was cancelled by the user during the authorisation process

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_CANCELLED",
 "error_message": "user cancelled the payment",
 "display_message": "Try making your payment again or select a different bank to continue.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_INSUFFICIENT\_FUNDS 

##### The account has insufficient funds to complete the payment. 

##### Sample user-facing error message 

Insufficient funds: There isn't enough money in this account to complete the payment. Try again, or select another account or bank.

##### Common causes 

*   The account selected has insufficient funds to complete the payment.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_INSUFFICIENT_FUNDS",
 "error_message": "insufficient funds to complete the request",
 "display_message": "There isn't enough money in this account to complete the payment. Try again, or select another account or bank.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_INVALID\_RECIPIENT 

##### The recipient was rejected by the chosen institution. 

##### Sample user-facing error message 

Payment failed: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The recipient name is too long or contains special characters.
*   The address is too long or contains special characters.
*   The account number is invalid.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_INVALID_RECIPIENT",
 "error_message": "payment recipient invalid",
 "display_message": "The payment recipient is invalid for the selected institution. Create a new payment with a different recipient.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_INVALID\_REFERENCE 

##### The reference was rejected by the chosen institution. 

##### Sample user-facing error message 

Payment failed: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The reference is too long or contains special characters.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_INVALID_REFERENCE",
 "error_message": "payment reference invalid",
 "display_message": "The payment reference is invalid for the selected institution. Create a new payment with a different reference.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_INVALID\_SCHEDULE 

##### The schedule was rejected by the chosen institution. 

##### Sample user-facing error message 

Payment failed: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The chosen institution does not support negative payment execution days.
*   The first payment date is a holiday or on a weekend.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_INVALID_SCHEDULE",
 "error_message": "payment schedule invalid",
 "display_message": "The payment schedule is invalid for the selected institution. Create a new payment with a different schedule.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_REJECTED 

##### The payment was rejected by the chosen institution. 

##### Sample user-facing error message 

Payment failed: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The amount was too large.
*   The payment was considered suspicious by the institution.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_REJECTED",
 "error_message": "payment rejected",
 "display_message": "The payment was rejected by the institution. Try again, or select another account or bank.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_SCHEME\_NOT\_SUPPORTED 

##### The requested payment scheme is not supported by the chosen institution. 

##### Sample user-facing error message 

Payment failed: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The payment scheme specified when calling [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) is not supported by the institution.
*   Scheme automatic downgrade failed.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_SCHEME_NOT_SUPPORTED",
 "error_message": "payment scheme not supported",
 "display_message": "The payment scheme is not supported by the institution. Either change scheme or select another institution.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_CONSENT\_INVALID\_CONSTRAINTS 

##### The payment consent constraints are missing or not supported by the institution. 

##### Sample user-facing error message 

Payment failed: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The payment consent constraints specified when calling [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) are not supported by the institution.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_CONSENT_INVALID_CONSTRAINTS",
 "error_message": "payment consent constraints invalid",
 "display_message": "The payment consent constraints are missing or not supported by the institution. Either update constraints or select another institution.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### PAYMENT\_CONSENT\_CANCELLED 

##### The payment consent was cancelled. 

##### Sample user-facing error message 

Payment cancelled: Try making your payment again or select a different bank to continue.

##### Common causes 

*   The payment consent was cancelled by the user during the authorisation process.

##### Troubleshooting steps 

API error responseLink error preview

```json
http code 400
{
 "error_type": "PAYMENT_ERROR",
 "error_code": "PAYMENT_CONSENT_CANCELLED",
 "error_message": "user cancelled the payment consent",
 "display_message": "Authorise your payment consent again or select a different bank to continue.",
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Rate Limit Exceeded errors | Plaid Docs

Rate Limit Exceeded Errors 
===========================

#### Guide to troubleshooting rate limit exceeded errors 

#### Rate limit table 

Errors of type `RATE_LIMIT_EXCEEDED` will occur when the rate limit for a particular endpoint has been exceeded. Default rate limit thresholds for some of the most commonly rate-limited endpoints are shown below. Note that these tables are not an exhaustive listing of all Plaid rate limits or rate-limited endpoints, that some customers may experience different rate limit thresholds from those shown, and that rate limits are subject to change at any time.

In general, Plaid default rate limits are set such that using the API as designed should typically not cause a rate limit to be encountered. If your use case requires a higher rate limit, contact your Account Manager or file a [Support request](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/product-functionality) .

##### Production rate limits 

| Endpoint | Max requests per Item | Max requests per client |
| --- | --- | --- |
| [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) | 5 per minute | 1,200 per minute |
| [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) | 15 per minute | 15,000 per minute |
| [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) | 5 per minute | 50 per minute |
| [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) | 15 per minute (per asset report) | 1,000 per minute |
| [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) | 15 per minute (per asset report) | 50 per minute |
| [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) | 5 per minute (per asset report) | 50 per minute |
| [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) | 15 per minute | 12,000 per minute |
| `/cra/check_report/*` | N/A | 100 per minute |
| `/cra/monitoring_insights/*` | N/A | 100 per minute |
| [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) | 15 per minute | 2,000 per minute |
| [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) | N/A | 200 per minute |
| [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) | N/A | 500 per minute |
| [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) | N/A | 400 per minute |
| [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) | N/A | 200 per minute |
| [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) | N/A | 50 per minute |
| [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) | N/A | 400 per minute |
| [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) | 15 per minute | 2,000 per minute |
| [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) | 30 per minute | 20,000 per minute |
| [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | 15 per minute | 5,000 per minute |
| [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) | 30 per minute | 2,000 per minute |
| [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) | 15 per minute | 1,000 per minute |
| [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) | N/A | 1,000 per minute |
| [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | N/A | 500 per minute |
| [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) | 70 per hour, 10 per transaction per hour | 20 per second |
| [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) | N/A | 4,000 per minute |
| [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) | N/A | 2,000 per minute |
| [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) | N/A | 4,000 per minute |
| [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) | N/A | 100 per minute |
| [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | 30 per minute | 20,000 per minute |
| [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) | 20 per minute | 1,000 per minute |
| [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) | 2 per minute | 100 per minute |
| [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | 50 per minute | 2,500 per minute |
| [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | 100 per hour | 2,500 per minute |
| [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | N/A | 250 per minute |
| [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | N/A | 2,500 per minute |
| [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) | N/A | 5,000 per minute |
| [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | N/A | 5,000 per minute |
| [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) | N/A | 250 per minute |
| [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) | N/A | 250 per minute |
| [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | N/A | 5,000 per minute |
| [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) | N/A | 250 per minute |
| [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | N/A | 5,000 per minute |
| `/transfer/*/get` | N/A | 5,000 per minute |
| `/transfer/*/list` | N/A | 100 per minute |
| `/watchlist_screening/*` | N/A | 2,000 per minute |
| [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) | N/A | 240 per minute |
| [/payment\_initiation/recipient/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientget) | N/A | 240 per minute |
| [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) | N/A | 240 per minute |
| [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) | N/A | 240 per minute |
| [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) | N/A | 240 per minute |
| [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) | N/A | 240 per minute |
| [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | N/A | 240 per minute |
| [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) | N/A | 100 per minute |
| [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) | N/A | 240 per minute |
| [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) | N/A | 100 per minute |
| [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) | N/A | 100 per minute (5 per consent) |

##### Sandbox rate limits 

| Endpoint | Max requests per Item | Max requests per client |
| --- | --- | --- |
| [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) | 25 per minute | 100 per minute |
| [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) | 100 per minute | 5,000 per minute |
| [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) | N/A | 100 per minute |
| [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) | 1,000 per minute | 1,000 per minute |
| [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) | N/A | 100 per minute |
| [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) | 100 per minute | 500 per minute |
| `/cra/check_report/*` | N/A | 100 per minute |
| `/cra/monitoring_insights/*` | N/A | 100 per minute |
| [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) | 100 per minute | 1,000 per minute |
| `/identity_verification/*` | N/A | 60 per minute |
| [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) | N/A | 10 per minute |
| [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) | N/A | 400 per minute |
| [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) | 100 per minute | 1,000 per minute |
| [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) | 100 per minute | 1,000 per minute |
| [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | 40 per minute | 5,000 per minute |
| [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) | 100 per minute | 500 per minute |
| [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) | 10 per minute | 1,000 per minute |
| [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) | N/A | 1,000 per minute |
| [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | N/A | 500 per minute |
| [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) | 70 per hour, 10 per transaction per hour | 30 per second |
| [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) | N/A | 4,000 per minute |
| [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) | N/A | 2,000 per minute |
| [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) | N/A | 4,000 per minute |
| [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) | N/A | 100 per minute |
| [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | 80 per minute | 1,000 per minute |
| [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) | 20 per minute | 1,000 per minute |
| [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) | 2 per minute | 100 per minute |
| [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | 50 per minute | 1,000 per minute |
| [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) | 2 per minute | 50 per minute |
| [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | 100 per hour | 100 per minute |
| [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | N/A | 100 per minute |
| [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | N/A | 100 per minute |
| [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | N/A | 100 per minute |
| [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | N/A | 100 per minute |
| `/watchlist_screening/*` | N/A | 500 per minute |
| [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) | N/A | 240 per minute |
| [/payment\_initiation/recipient/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientget) | N/A | 240 per minute |
| [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) | N/A | 240 per minute |
| [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) | N/A | 100 per minute |
| [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) | N/A | 240 per minute |
| [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) | N/A | 240 per minute |
| [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | N/A | 240 per minute |
| [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) | N/A | 100 per minute |
| [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) | N/A | 240 per minute |
| [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) | N/A | 100 per minute |
| [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) | N/A | 100 per minute (10 per consent) |

#### ACCOUNTS\_LIMIT 

##### Too many requests were made to the /accounts/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) in Production are rate limited at a maximum of 15 requests per Item per minute and 15,000 per client per minute. In the Sandbox, they are limited at a maximum of 100 per Item per minute and 5,000 per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "ACCOUNTS_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ACCOUNTS\_BALANCE\_GET\_LIMIT 

##### Too many requests were made to the /accounts/balance/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time by a single client. Requests to `/account/balance/get` in Production are client rate limited to 1,200 requests per client per minute. In the Sandbox environment, they are client rate limited at a maximum of 100 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "ACCOUNTS_BALANCE_GET_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### AUTH\_LIMIT 

##### Too many requests were made to the /auth/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) in Production are rate limited at a maximum of 15 requests per Item per minute and 12,000 per client per minute. In the Sandbox, they are rate limited at a maximum of 100 requests per Item per minute and 500 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "AUTH_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### BALANCE\_LIMIT 

##### Too many requests were made to the /accounts/balance/get endpoint. 

##### Common causes 

*   Too many requests were made for a single Item in a short period of time. Requests to `/account/balance/get` in Production are Item rate limited at a maximum of 5 requests per Item per minute. In the Sandbox environment, they are Item rate limited at a maximum of 25 requests per Item per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "BALANCE_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### CREDITS\_EXHAUSTED 

##### You have used up your free API usage allocation in Limited Production 

##### Common causes 

*   You ran out of free API calls for a given product in Limited Production.
*   You do not yet have Production access and hit the Item creation cap in Limited Production.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "CREDITS_EXHAUSTED",
 "error_message": "Free usage exhausted, please request full Production access to continue using this product",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### IDENTITY\_LIMIT 

##### Too many requests were made to the /identity/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) in Production are rate limited at a maximum of 15 requests per Item per minute and 2,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 100 requests per Item per minute and 1,000 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "IDENTITY_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTIONS\_GET\_LIMIT 

##### Too many requests were made to the /institutions/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) in Production are rate limited at a maximum of 25 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 10 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "INSTITUTIONS_GET_LIMIT",
 "error_message": "rate limit exceeded for attempts to access \"institutions get by id\". please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTIONS\_GET\_BY\_ID\_LIMIT 

##### Too many requests were made to the /institutions/get\_by\_id endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) are rate limited at a maximum of 400 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "INSTITUTIONS_GET_BY_ID_LIMIT",
 "error_message": "rate limit exceeded for attempts to access \"institutions get by id\". please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INSTITUTION\_RATE\_LIMIT 

##### Too many requests were made to a given institution. 

##### Common causes 

*   Too many requests were made by Plaid in a short period of time to a given institution. Because each institution has unique rate limiting behavior, Plaid cannot provide exact details of how many requests are necessary to trigger this behavior.
*   This error will only trigger when calling API endpoints that request realtime data from the institution, such as [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) or [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) .
*   This institution-level limit is distinct from per-Item or per-client limits and is not applied to user-present traffic (e.g., within Link).
*   In some cases, the cause of the rate limit may be another client and may not be your client application's behavior.

##### Troubleshooting steps 

If your client made a very large number of requests in a short time to a realtime endpoint such as [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) at a single institution, consider adding logic to spread these requests over a longer time window.

Use an exponential backoff retry algorithm to try your request again later.

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "INSTITUTION_RATE_LIMIT",
 "error_message": "The institution is currently receiving too many requests. Please try again later.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVESTMENT\_HOLDINGS\_GET\_LIMIT 

##### Too many requests were made to the /investments/holdings/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) in Production are rate limited at a maximum of 15 requests per Item per minute and 2,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 100 requests per Item per minute and 1,000 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "INVESTMENT_HOLDINGS_GET_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INVESTMENT\_TRANSACTIONS\_LIMIT 

##### Too many requests were made to the /investments/transactions/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) in Production are rate limited at a maximum of 30 requests per Item per minute and 20,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 100 requests per Item per minute and 1,000 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "INVESTMENT_TRANSACTIONS_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ITEM\_GET\_LIMIT 

##### Too many requests were made to the /item/get endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) in Production are rate limited at a maximum of 15 requests per Item per minute and 5,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 40 requests per Item per minute and 5,000 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "ITEM_GET_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### RATE\_LIMIT 

##### Too many requests were made. 

##### Common causes 

*   Too many requests were made in a short period of time.
*   Sandbox credentials (the username `user_good` or `user_custom`) were used to attempt to log in to Production. Because using these credentials in a live environment is a common misconfiguration, they are frequently subject to rate limiting.
*   A Link attempt was detected as potential attempted abuse. For example, this may occur if a user enters their credentials incorrectly too many times in a row.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "RATE_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTIONS\_LIMIT 

##### Too many requests were made to a transactions endpoint such as/transactions/get or /transactions/refresh. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) in Production are rate limited at a maximum of 30 requests per Item per minute and 20,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 80 requests per Item per minute and 1,000 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "TRANSACTIONS_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTIONS\_SYNC\_LIMIT 

##### Too many requests were made to the /transactions/sync endpoint. 

##### Common causes 

*   Too many requests were made in a short period of time. Requests to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) in Production are rate limited at a maximum of 50 requests per Item per minute and 2,500 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 50 requests per Item per minute and 1,000 requests per client per minute.

##### Troubleshooting steps 

```json
http code 429
{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "error_code": "TRANSACTIONS_SYNC_LIMIT",
 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Recaptcha errors | Plaid Docs

ReCAPTCHA Errors 
=================

#### Guide to troubleshooting reCAPTCHA errors 

#### RECAPTCHA\_REQUIRED 

##### The request was flagged by Plaid's fraud system, and requires additional verification to ensure they are not a bot. 

##### Link user experience 

Your user will be prompted to solve a [Google reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html) challenge in the Link `Recaptcha` pane. If they solve the challenge successfully, the user's request is resubmitted and they are directed to the next Item creation step.

##### Common causes 

*   Plaid's fraud system detects abusive traffic and considers a variety of parameters throughout Item creation requests. When a request is considered risky or possibly fraudulent, Link presents a reCAPTCHA for the user to solve.

##### Troubleshooting steps 

Link will automatically guide your user through reCAPTCHA verification. As a general rule, we recommend instrumenting basic fraud monitoring to detect and protect your website from spam and abuse.

If your user cannot verify their session, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `link_session_id` or `request_id`.

```json
http code 400
{
 "error_type": "RECAPTCHA_ERROR",
 "error_code": "RECAPTCHA_REQUIRED",
 "error_message": "This request requires additional verification. Please resubmit the request after completing the challenge",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### RECAPTCHA\_BAD 

##### The provided challenge response was denied. 

##### Sample user-facing error message 

Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time

##### Link user experience 

If after several failed attempts your user is still unable to solve the reCAPTCHA challenge, the `RECAPTCHA_BAD` error is returned and they are directed to the `InstitutionSelect` pane to connect a new account.

##### Common causes 

*   The user was unable to successfully solve the presented reCAPTCHA problem after several attempts.
*   The current session is a bot or other malicious software.

##### Troubleshooting steps 

If your user cannot verify their session, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `link_session_id` or `request_id`.

API error responseLink error preview

```json
http code 400
{
 "error_type": "RECAPTCHA_ERROR",
 "error_code": "RECAPTCHA_BAD",
 "error_message": "The provided challenge response was denied. Please try again",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Sandbox errors | Plaid Docs

Sandbox Errors 
===============

#### Guide to troubleshooting Sandbox errors 

#### SANDBOX\_PRODUCT\_NOT\_ENABLED 

##### The requested product is not enabled for an Item 

##### Common causes 

*   A sandbox operation could not be performed because a product has not been enabled on the Sandbox Item.

##### Troubleshooting steps 

If the error persists, submit a [Support](https://dashboard.plaid.com/support/new/) ticket.

```json
http code 400
{
 "error_type": "SANDBOX_ERROR",
 "error_code": "SANDBOX_PRODUCT_NOT_ENABLED",
 "error_message": "The [auth | transactions | ...] product is not enabled on this item",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### SANDBOX\_WEBHOOK\_INVALID 

##### The request to fire a Sandbox webhook failed. 

##### Common causes 

*   The webhook for the Item sent in the [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) request is not set or is invalid.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "SANDBOX_ERROR",
 "error_code": "SANDBOX_WEBHOOK_INVALID",
 "error_message": "Webhook for this item is either not set up, or invalid. Please update the item's webhook and try again.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### SANDBOX\_TRANSFER\_EVENT\_TRANSITION\_INVALID 

##### The /sandbox/transfer/simulate endpoint was called with parameters specifying an invalid event transition. 

##### Common causes 

*   The [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) endpoint was called with parameters specifying an invalid event transition.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "SANDBOX_ERROR",
 "error_code": "SANDBOX_TRANSFER_EVENT_TRANSITION_INVALID",
 "error_message": "The provided simulated event type is incompatible with the current transfer status",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Transactions errors | Plaid Docs

Transactions errors 
====================

#### Guide to troubleshooting Transactions errors 

#### TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION 

##### Transaction data was updated during pagination. 

##### Common causes 

*   Transaction data was updated during pagination. This can occur when calling the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTIONS_ERROR",
 "error_code": "TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION",
 "error_message": "Underlying transaction data changed since last page was fetched. Please restart pagination from last update.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Errors - Transfer errors | Plaid Docs

Transfer errors 
================

#### Errors specific to the Transfer product 

#### TRANSFER\_NETWORK\_LIMIT\_EXCEEDED 

##### The attempted transfer exceeded the given network's amount limit. 

##### Common causes 

*   The attempted transfer's amount exceeded the network specific limit. The error message will indicate which network limit was exceeded. For reference, see the table below.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_NETWORK_LIMIT_EXCEEDED",
 "error_message": "[network] transaction amount cannot exceed [amount]",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

| Network | Maximum Transaction Limit |
| --- | --- |
| ACH | $10,000,000.00 |
| Same Day ACH | $1,000,000.00 |
| RTP | $1,000,000.00 |
| RfP | $3,500.00 |
| Wire | $999,999.99 |

#### TRANSFER\_ACCOUNT\_BLOCKED 

##### The transfer could not be completed because a previous transfer involving the same end-user account resulted in an error 

##### Common causes 

*   Plaid has flagged the end-user's account as not valid for use with Transfer.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_ACCOUNT_BLOCKED",
 "error_message": "transfer was blocked due to a previous ACH return on this account",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSFER\_NOT\_CANCELLABLE 

##### The transfer could not be canceled 

##### Common causes 

*   An attempt was made to cancel a transfer that has already been sent to the network for execution and cannot be cancelled at this stage.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_NOT_CANCELLABLE",
 "error_message": "transfer is not cancellable",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSFER\_UNSUPPORTED\_ACCOUNT\_TYPE 

##### An attempt was made to transfer funds to or from an unsupported account type 

##### Common causes 

*   An attempt was made to transfer funds to or from an unsupported account type. Only checking, savings, and cash management accounts can be used with Transfer. In addition, if the transfer is a debit transfer, the account must be a debitable account. Common examples of non-debitable depository accounts include savings accounts at Chime or at Navy Federal Credit Union (NFCU).

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_UNSUPPORTED_ACCOUNT_TYPE",
 "error_message": "transfer account type not supported",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSFER\_FORBIDDEN\_ACH\_CLASS 

##### An attempt was made to create a transfer with a forbidden ACH class (SEC code) 

##### Common causes 

*   Your Plaid account has not been enabled for the ACH class specified in the request.
    
*   The ACH class specified in the transfer request was incorrect.
    

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_FORBIDDEN_ACH_CLASS",
 "error_message": "specified ach_class is forbidden",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSFER\_UI\_UNAUTHORIZED 

##### The client is not enabled for the Transfer UI product 

##### Common causes 

*   Your account is not enabled for use with Transfer UI.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_UI_UNAUTHORIZED",
 "error_message": "client is not authorized for transfer UI",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSFER\_ORIGINATOR\_NOT\_FOUND 

##### An association between the sender and the originator client doesn't exist 

##### Common causes 

*   There is a typo in the `originator_client_id`
*   You are a Platform Payments customer (not a partner) and did not call [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) for this end-customer
*   You are a Plaid Partner and have not submitted diligence information via [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) for this end-customer

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "TRANSFER_ORIGINATOR_NOT_FOUND",
 "error_message": "the association between the sender and the originator client doesn't exist",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### INCOMPLETE\_CUSTOMER\_ONBOARDING 

##### The end customer has not completed onboarding. Their diligence status must be approved before moving funds 

##### Common causes 

*   You tried to move funds for an originator that hasn't been approved by Plaid yet

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "INCOMPLETE_CUSTOMER_ONBOARDING",
 "error_message": "end customer has not completed onboarding. their diligence status must be `approved` before moving funds",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### UNAUTHORIZED\_ACCESS 

##### You are not authorized to access this endpoint for your use case 

##### Common causes 

*   You are not a Platform Payments customer and tried to call a Platform Payments endpoint
*   You are a Plaid Partner and tried to create an end-customer using [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) (instead of [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) )

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSFER_ERROR",
 "error_code": "UNAUTHORIZED_ACCESS",
 "error_message": "you are not authorized to access this endpoint for your use case.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### ACH return codes 

Prefer to learn by watching? A [video guide](https://www.youtube.com/watch?v=7UqU2TGLiMc) is available for this topic.

All `returned` ACH transactions will have an ACH return code. By reading the code, you can troubleshoot and debug returned transactions.

[Transfer](https://plaid.com/docs/transfer/index.html.md) customers should see [Common ACH Return Codes in the Help Center](https://support.plaid.com/hc/en-us/articles/32881797799575-What-are-the-Common-ACH-Return-Codes) for more detailed information on troubleshooting ACH return codes.

| Return Code | Description | Notes |
| --- | --- | --- |
| R01 | Insufficient funds | Available balance is not sufficient to cover the dollar amount of the debit entry |
| R02 | Account closed | A previously open account is now closed |
| R03 | No account or unable to locate account | The account number structure is valid, but the account number does not correspond to an existing account, or the name on the transaction does not match the name on the account. |
| R04 | Invalid account number | The account number fails the check digit validation or may contain an incorrect number of digits. Commonly caused by invalidated TANs; see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) for more details. |
| R05 | Unauthorized debit to consumer account | A business debit entry was transmitted to a member’s consumer account, and the member had not authorized the entry |
| R06 | Returned per ODFI's request | The ODFI has requested that the RDFI return the entry |
| R07 | Authorization revoked by customer | Member who previously authorized an entry has revoked authorization with the originator |
| R08 | Payment stopped or stop payment on item | Member had previously requested a stop payment of a single or recurring entry |
| R09 | Uncollected funds | Available balance is sufficient, but the collected balance is not sufficient to cover the entry |
| R10 | Customer advises not authorized | Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document |
| R11 | Check truncation entry return | To be used when returning a check truncation entry |
| R12 | Branch sold to another DFI | RDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution |
| R13 | Invalid ACH routing number | Financial institution does not receive commercial ACH entries |
| R14 | Representative payee deceased or unable to continue in that capacity | Representative payee is deceased or unable to continue in that capacity, beneficiary is not deceased |
| R15 | Beneficiary of account holder deceased | Beneficiary or Account Holder Deceased |
| R16 | Account frozen | Access to account is restricted due to a specific action taken by the RDFI or by legal action |
| R17 | File record edit criteria | Fields rejected by RDFI processing (identified in return addenda) |
| R18 | Improper effective entry | Entries have been presented prior to the first available processing window for the effective date |
| R19 | Amount field error | Improper formatting of the amount field |
| R20 | Non-transaction account | Policies or regulations (such as Regulation D) prohibit or limit activity to the account indicated |
| R21 | Invalid company identification | The company ID information not valid (normally CIE entries) |
| R22 | Invalid individual ID number | Individual id used by receiver is incorrect (CIE entries) |
| R23 | Credit entry refused by receiver | Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account |
| R24 | Duplicate entry | RDFI has received a duplicate entry |
| R25 | Addenda error | Improper formatting of the addenda record information |
| R26 | Mandatory field error | Improper information in one of the mandatory fields |
| R27 | Trace number error | Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record |
| R28 | Routing number or check digit | Check digit for transit routing number is incorrect |
| R29 | Corporate customer advises not authorized | RDFI has been notified by business account holder that a specific transaction is unauthorized. Business accounts often automatically decline debits for security purposes. Your customer needs to inform their bank to allow debits that use your tax identifier. |
| R30 | RDFI not participant in check truncation program | Financial institution not participating in automated check safekeeping application |
| R31 | Permissible return entry | RDFI has been notified by business account holder that a specific transaction is unauthorized |
| R32 | RDFI non settlement | RDFI is not able to settle the entry |
| R33 | Return of XCK entry | RDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry |
| R34 | Limited participation DFI | RDFI participation has been limited by a federal or state supervisor |
| R35 | Return of improper debit entry | ACH debit not permitted for use with the CIE standard entry class code (except for reversals) |
| R36 | Return of improper credit entry |  |
| R37 | Source Document Presented for Payment | Check used for an ARC, BOC or POP entry has also been presented for payment |
| R38 | Stop payment on source document | Stop payment has been placed on a check used for an ARC entry |
| R40 | Return of ENR entry by federal government agency (ENR only) |  |
| R41 | Invalid transaction code (ENR only) |  |
| R42 | Routing number or check digit error (ENR only) |  |
| R43 | Invalid DFI account number (ENR only) |  |
| R44 | Invalid individual ID number (ENR only) |  |
| R45 | Invalid individual name/company name (ENR only) |  |
| R46 | Invalid representative payee indicator (ENR only) |  |
| R47 | Duplicate enrollment |  |
| R50 | State law affecting RCK acceptance |  |
| R51 | Item is ineligible, notice not provided, signature not genuine |  |
| R52 | Stop payment on item |  |
| R61 | Misrouted return | Return entry was sent by RDFI to an incorrect ODFI routing/transit number |
| R62 | Incorrect trace number |  |
| R63 | Incorrect dollar amount |  |
| R64 | Incorrect individual identification |  |
| R65 | Incorrect transaction code |  |
| R66 | Incorrect company identification |  |
| R67 | Duplicate return | ODFI has received more than one return entry for the same original entry |
| R68 | Untimely return | Return entry did not meet the return deadline |
| R69 | Multiple errors |  |
| R70 | Permissible return entry not accepted |  |
| R71 | Misrouted dishonored return |  |
| R72 | Untimely dishonored return |  |
| R73 | Timely original return |  |
| R74 | Corrected return |  |
| R80 | Cross-border payment coding error |  |
| R81 | Nonparticipant in cross-border program |  |
| R82 | Invalid foreign receiving DFI identification |  |

#### RTP/RfP error codes 

`failed` RTP/RfP transactions will have a failure description. By reading the description, you can troubleshoot and debug failed transactions.

This table can also be [viewed as a Google doc](https://docs.google.com/spreadsheets/d/12jHY-VZYtYqzSHQE6eEzy_I7ZbN4SLZcWTcdjoMAiuQ/edit?gid=123470926#gid=123470926) .

| Failure Code | Description | Rail(s) | Condensed Error Category | Retryable | Suggested Action |
| --- | --- | --- | --- | --- | --- |
| 1100 | Other Reasons - Not specified | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| 9909 | Central Switch system malfunction | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| 9910 | Instructed Agent signed-off | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| 9912 | Recipient connection unavailable | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| 9934 | Instructing Agent signed-off | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| 9946 | Instructing Agent suspended | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| 9947 | Instructed Agent suspended | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| 9948 | Central Switch service suspended | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. |
| AC02 | Debtor account is invalid | Both | Issues with the sending account | No | Ask the sender to correct or switch accounts, then resubmit. |
| AC03 | Creditor account is invalid | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AC04 | Account closed | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AC06 | Account is blocked | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AC07 | Creditor account closed | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AC13 | Debtor account type invalid | Both | Issues with the sending account | No | Ask the sender to correct or switch accounts, then resubmit. |
| AC14 | Creditor account type invalid | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AG01 | Transaction forbidden on this type of account | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AG03 | Transaction type not supported on this account | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| AM02 | Transaction amount exceeds allowed maximum | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| AM04 | Insufficient funds | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| AM09 | Incorrect amount received | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| AM12 | Amount invalid or missing | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| AM13 | Amount exceeds clearing system limits | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| AM14 | Amount exceeds bank-client limit | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| BE04 | Missing or incorrect creditor address | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| BE06 | End customer not known | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| BE07 | Missing or incorrect debtor address | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| BE16 | Debtor identification invalid | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| BE17 | Creditor identification invalid | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| BLKD | Payment has been blocked | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| CH11 | Creditor identifier unknown | RFP | Authorization declined or customer action required | No | Respect customer’s decision or obtain new authorization. |
| CUST | Customer declined payment | Both | Authorization declined or customer action required | No | Respect customer’s decision or obtain new authorization. |
| DS04 | Order rejected – content issues | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| DS0H | Signer not authorized for this account | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| DS24 | Waiting time expired (incomplete order) | Both | Authorization declined or customer action required | Yes - after correction | Respect customer’s decision or obtain new authorization. |
| DT04 | Future date not supported | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| DUPL | Duplicate payment detected | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| FF02 | Syntax error in narrative information | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| FF03 | Invalid payment type information | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| FF08 | End‑to‑End ID missing or invalid | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| INSF | Insufficient funds for outbound message | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| MD07 | End customer is deceased | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. |
| NARR | Narrative reason provided | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| NOAT | Account does not support this message type | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| RC01 | Bank identifier format incorrect | Both | Routing or bank identifier issue | Yes - after correction | Supply a valid routing/BIC and retry. |
| RC02 | Bank identifier invalid or missing | Both | Routing or bank identifier issue | Yes - after correction | Supply a valid routing/BIC and retry. |
| RC03 | Debtor FI identifier invalid or missing | Both | Routing or bank identifier issue | Yes - after correction | Supply a valid routing/BIC and retry. |
| RC04 | Creditor FI identifier invalid or missing | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. |
| SL12 | Debtor opted out of RFPs | RFP | Authorization declined or customer action required | No | Respect customer’s decision or obtain new authorization. |
| TK01 | Invalid token | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK02 | Sender token not found | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK03 | Receiver token not found | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK04 | Token expired | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK05 | Token counterparty mismatch | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK06 | Token value‑limit rule violation | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK07 | Single‑use token already used | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |
| TK08 | Token suspended | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. |

---


# Errors - Virtual Accounts errors (Europe) | Plaid Docs

Virtual Account(UK/EU) Errors 
==============================

#### TRANSACTION\_INSUFFICIENT\_FUNDS 

##### Common Causes 

*   The account does not have sufficient funds to complete the transaction.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_INSUFFICIENT_FUNDS",
 "error_message": "There are insufficient funds to complete the transaction",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_AMOUNT\_EXCEEDED 

##### Common Causes 

*   The transaction amount exceeds the allowed threshold configured for this client.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_AMOUNT_EXCEEDED",
 "error_message": "Transaction amount exceeds the allowed threshold for this client",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_ON\_SAME\_ACCOUNT 

##### Common Causes 

*   The recipient bank account details on the transaction are incorrect and refer to the source Virtual Account.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_ON_SAME_ACCOUNT",
 "error_message": "Payment to the same account is not allowed",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_CURRENCY\_MISMATCH 

##### Common Causes 

*   The currency on the recipient bank account is different than that of the wallet.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_CURRENCY_MISMATCH",
 "error_message": "The currency between the wallet and recipient account is different",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_IBAN\_INVALID 

##### Common Causes 

*   The provided IBAN on the recipient bank account is invalid.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_IBAN_INVALID",
 "error_message": "The provided IBAN is invalid",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_BACS\_INVALID 

##### Common Causes 

*   The provided Account Number and/or Sort Code on the recipient account is invalid.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_BACS_INVALID",
 "error_message": "The provided BACS account number and/or sort code is invalid",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_FAST\_PAY\_DISABLED 

##### Common Causes 

*   The provided Sort Code on the recipient account is not enabled for Faster Payments. GBP transactions out of Virtual Accounts in GB are made via the Faster Payments rail.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_FAST_PAY_DISABLED",
 "error_message": "The recipient sort code is not enabled for faster payments",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### TRANSACTION\_EXECUTION\_FAILED 

##### Common Causes 

*   The transaction failed to execute due to an internal error.
*   The transaction might have been declined by the receiving bank.
*   Technical issues with the payment processor.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "TRANSACTION_EXECUTION_FAILED",
 "error_message": "There was a problem executing the transaction. Please retry.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### NONIDENTICAL\_REQUEST 

##### Common Causes 

*   The request parameters have changed compared to the original request with the same idempotency key.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "NONIDENTICAL_REQUEST",
 "error_message": "Request body does not match previous request with this idempotency key",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

#### REQUEST\_CONFLICT 

##### Common Causes 

*   The original request is still processing and has not completed.
*   A network or system issue caused a delay in processing the original request, resulting in a conflict when the new request is sent.

##### Troubleshooting steps 

```json
http code 400
{
 "error_type": "TRANSACTION_ERROR",
 "error_code": "REQUEST_CONFLICT",
 "error_message": "Original request is still processing",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}
```

---


# Financial Insights | Plaid Docs

Financial insights products 
============================

#### Review and compare solutions 

This page provides overviews of Plaid's financial insights solutions to help you find the right one for your needs.

These products serve use cases such as personal finance and budgeting, loan payback and debt management, expense and accounting applications, and wealth management and investing. Note that none of these products may be used as part of a credit or underwriting decisioning process; for underwriting use cases, see [credit underwriting products](https://plaid.com/docs/underwriting/index.html.md) .

#### Transactions 

[Transactions](https://plaid.com/docs/transactions/index.html.md) gets transaction data for an end user's account, such as a checking, savings, or credit card account. Transaction data includes details such as date, merchant, and category; for some transactions, it will also include location data and a merchant name that has been enhanced for greater human readability. Any transaction data fields not provided to Plaid directly by the financial institution are derived via Plaid's ML-powered transactions enrichment engine. New and updated transactions are typically extracted between one and four times per day, depending on the institution.

##### Transactions Refresh 

[Transactions Refresh](https://plaid.com/docs/transactions/index.html.md) is an optional add-on for Transactions that can be used to trigger an on-demand, real-time update of transactions data. Transactions Refresh provides on-demand updates only; Plaid does not offer a real-time feed of transactions updates.

##### Recurring Transactions 

[Recurring Transactions](https://plaid.com/docs/transactions/index.html.md#recurring-transactions) , available in the US, CA, and UK, is an optional add-on for Transactions that can be used to identify recurring transaction streams. Recurring Transactions is typically used by financial management apps to power features such as budget analysis and helping users identify and cancel unwanted subscriptions.

#### Enrich 

[Enrich](https://plaid.com/docs/enrich/index.html.md) allows you to provide your own transactions data and uses the same ML-powered enrichment engine used by the Transactions product to enhance this data with more details, such as category, location, and merchant name. Unlike most other Plaid products, Enrich does not use Link to connect to an end user's financial account; Enrich is designed for customers who already have transactions data from a non-Plaid source and would like to enhance it to provide better insights to their customers.

#### Liabilities 

[Liabilities](https://plaid.com/docs/liabilities/index.html.md) gets details about an end user's debt, including interest rate, outstanding balance, repayment schedule, and details of the most recent repayment. Supported loan types are credit cards, private student loans, mortgages, and PayPal loans. Liabilities does not provide transaction history. For full transaction and loan details, use both Liabilities and Transactions together.

#### Investments 

[Investments](https://plaid.com/docs/investments/index.html.md) gets details about an end user's investment account, such as a brokerage account or 401(k). Investments comes with access to two main features: Investments Holdings, which provides details on the specific assets held, including type, description, value, cost basis, and acquisition date; and Investments Transactions, which provides details on transactions (such as trades, transfers, or dividends) within an investment account.

##### Investments Refresh 

[Investments Refresh](https://plaid.com/docs/investments/index.html.md) is an optional add-on for Investments that can be used to trigger an on-demand, real-time update of investments data.

#### Transactions, Investments, Liabilities, and Enrich comparison table 

|  | Transactions | Investments | Liabilities | Enrich |
| --- | --- | --- | --- | --- |
| Summary | Details on transactions | Details on investments and investments transactions | Details on loans, payments, balances, and interest | Enrich your existing transactions data |
| Main supported account types | Checking, savings, credit cards | Brokerage accounts, including retirement | Credit cards, private student loans, mortgages | Checking, savings, credit cards |
| Supports brokerage accounts | No | Yes | No | No |
| Provides transaction details | Yes | Yes | No (only most recent payment) | N/A |
| Provides ML-enhanced transaction descriptions and details | Yes | No | No | Yes |
| Provides interest rates | No | No | Yes | No |
| Typical update frequency | 1-4 times per day | Once per day, after market close | Once per day | N/A |
| Optional Refresh add-on for on-demand updates | Yes | Yes | No | N/A |
| Supported countries | US, CA, UK, Europe | US | US, CA (CA coverage limited) | US, CA |
| Billing plans available | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract |

---


# Identity Verification - Input validation rules | Plaid Docs

Input validation rules 
=======================

Identity Verification does as much as possible to ensure the user data it helps you collect and verify is clean and standardized. If you're getting all your user data for Identity Verification entirely from the Link flow, then you don't need to worry about the validations described below. If you are submitting data about the user via the API (e.g. for a [hybrid](https://plaid.com/docs/identity-verification/index.html.md#streamlining-link-by-pre-populating-user-information-hybrid-link-flow) or [fully API-based](https://plaid.com/docs/identity-verification/index.html.md#data-source-checks-without-ui-backend-flow) verification approach), you will need to match the formatting and standardization requirements described below.

To help with development, we also provide a [JSON file containing the same validation rules](https://plaid.com/schema/identity_verification_api.json) .

#### ID numbers 

Plaid's Data Source Verification will automatically collect, validate, and verify any of the following ID numbers for countries that you've enabled in the Dashboard Editor.

If you are separately collecting ID numbers outside of Link, or if you have existing customer data you're looking to import into Plaid, you can submit this data to the Identity Verification API programmatically via [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) or the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `user` object.

The table below lists each ID number that Identity Verification supports. The `API type` is a unique identifier that you should provide via API via the `id_number.type` field.

ID Numbers submitted via API should be stripped of any formatting characters like spaces, periods, and dashes. The table below also includes the exact regular expressions we use to decide whether a given ID Number is well-formed and valid for that region's ID type.

Plaid may perform additional validation to ensure the ID number is valid for the selected type. For example, the SSA will not issue SSNs with specific numbers in certain positions. SSNs that meet any of the following conditions will not be accepted:

*   Begin with “9”, “666”, or “000”
*   Have the number “00" in positions 4 – 5
*   Have the number “0000” in positions 6 – 9

_Need this data for your code? [Download these validation rules in JSON form](https://plaid.com/schema/identity_verification_api.json)_

| Country | Country Code | ID Name | API Type | Format |
| --- | --- | --- | --- | --- |
| Argentina | `AR` | Documento Nacional de Identidad (DNI) | `ar_dni` | `\A\d{8,10}\z` |
| Australia | `AU` | Driver’s License | `au_drivers_license` | `\A[A-Z0-9]{6,11}\z` |
| Australia | `AU` | Passport Number | `au_passport` | `\A[A-Z0-9]{7,9}\z` |
| Brazil | `BR` | Cadastro de Pessoas Físicas (CPF) | `br_cpf` | `\A\d{11}\z` |
| Canada | `CA` | Social Insurance Number (SIN) | `ca_sin` | `\A\d{9}\z` |
| Chile | `CL` | Rol Único Nacional (RUN) | `cl_run` | `\A\d{7,8}[0-9Kk]\z` |
| China | `CN` | Resident Identity Card Number | `cn_resident_card` | \`\\A\\d{15} |
| Colombia | `CO` | Número de Identificación Tributaria (NIT) | `co_nit` | `\A\d{8,10}\z` |
| Denmark | `DK` | Civil Personal Registration (CPR) | `dk_cpr` | `\A\d{9,11}\z` |
| Egypt | `EG` | National ID Card Number | `eg_national_id` | `\A\d{14}\z` |
| Hong Kong | `HK` | Hong Kong Identity (HKID) | `hk_hkid` | `\A[A-Z0-9]{8,9}\z` |
| India | `IN` | Permanent Account Number (PAN) | `in_pan` | `\A[A-Z]{5}\d{4}[A-Z]\z` |
| India | `IN` | Voter ID (EPIC) | `in_epic` | `\A[A-Z]{3}\d{7}\z` |
| Italy | `IT` | Codice Fiscale (CF) | `it_cf` | `\A[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]\z` |
| Japan | `JP` | "My Number" Resident Record Code | `jp_my_number` | `\A\d{12}\z` |
| Jordan | `JO` | Civil Identification Number | `jo_civil_id` | `\A\d{10,14}\z` |
| Kenya | `KE` | Huduma Namba | `ke_huduma_namba` | `\A\d{10}\z` |
| Kuwait | `KW` | Civil ID Card Number | `kw_civil_id` | `\A\d{12}\z` |
| Malaysia | `MY` | National Registration Identity Card Number (NRIC) | `my_nric` | `\A\d{12}\z` |
| Mexico | `MX` | Clave Única de Registro de Población (CURP) | `mx_curp` | `\A[A-Z]{4}\d{6}[A-Z]{6}[A-Z\d]\d\z` |
| Mexico | `MX` | Registro Federal de Contribuyentes (RFC) | `mx_rfc` | `\A[A-Z]{4}\d{6}[A-Z\d]{3}\z` |
| New Zealand | `NZ` | Driver’s License | `nz_drivers_license` | `\A[A-Z]{2}\d{6}\z` |
| Nigeria | `NG` | National ID Number | `ng_nin` | `\A\d{11}\z` |
| Oman | `OM` | Identity Card Number | `om_civil_id` | `\A\d{8,9}\z` |
| Philippines | `PH` | PhilSys Number | `ph_psn` | `\A\d{12}\z` |
| Poland | `PL` | PESEL Number | `pl_pesel` | `\A\d{11}\z` |
| Romania | `RO` | Cod Numeric Personal (CNP) | `ro_cnp` | `\A\d{13}\z` |
| Saudi Arabia | `SA` | Biṭāgat Al-ʼaḥwāl | `sa_national_id` | `\A[A-Z0-9]{10}\z` |
| Singapore | `SG` | National Registration Identity Card | `sg_nric` | `\A[A-Z]\d{7}[A-Z]\z` |
| South Africa | `ZA` | Smart ID Card Number | `za_smart_id` | `\A\d{13}\z` |
| Spain | `ES` | Documento Nacional de Identidad (DNI) | `es_dni` | `\A\d{8}[A-Z]\z` |
| Spain | `ES` | Número de Identidad de Extranjero (NIE) | `es_nie` | `\A[A-Z]\d{7}[A-Z]\z` |
| Sweden | `SE` | Personnummer (PIN) | `se_pin` | `\A\d{9,12}\z` |
| Turkey | `TR` | T.C. Kimlik No. | `tr_tc_kimlik` | `\A\d{11}\z` |
| United States | `US` | Social Security Number (SSN or ITIN) | `us_ssn` | `\A\d{9}\z` |
| United States | `US` | Social Security Number (SSN or ITIN) Last 4 | `us_ssn_last_4` | `\A\d{4}\z` |

#### Input validation by country 

Address standards vary by country. Some countries do not support postal code or region (the equivalent of "state" or "province" depending on the region). In other countries, postal code and/or region is valid in a sense, but superfluous and not typically collected in native forms.

Separately, variations in identity data coverage mean that collection of "ID Number" is a required part of Data Source Verification in some countries, optional (configured in the Dashboard Editor) for other countries, and not supported in countries that do not support Data Source Verification at all.

This regional variation is reflected in the table below.

The labels for each input field below correspond to the following input validations:

*   `address.postal_code` and `address.region`
    
    *   **Required** - If `address` is provided as part of the request, this field must always be present
        
    *   **Not Accepted** - If `address` is provided as part of the request, this field must be omitted. Specifically, the key should be omitted from the `address` object (as opposed to the key being present with a null value)
        
*   `id_number`
    
    *   **Required** - If `id_number` is not provided for this country, `kyc_check` will treat the Identity Verification Session as having incomplete data and will require user interaction with the Identity Verification modal in order to collect `id_number`
        
    *   **Optional** - If `id_number` is not provided for this country **and** your Identity Verification Template is configured to not collect ID numbers for this country then Identity Verification will automatically run the `kyc_check` step without any user interaction as long as all other required input fields are provided. Similar to the address fields, the API requires you omit the `id_number` key entirely if you are not providing ID number data
        
    *   **Not Accepted** - ID number verification is not supported for this country and the `id_number` field should always be omitted from API requests
        

_Need this data for your code? [Download these validation rules in JSON form](https://plaid.com/schema/identity_verification_api.json)_

| Country | Country Code | `address.postal_code` | `address.subdivision` | `id_number` |
| --- | --- | --- | --- | --- |
| Afghanistan | `AF` | Required | Not Accepted | Not Accepted |
| Albania | `AL` | Required | Not Accepted | Not Accepted |
| Algeria | `DZ` | Required | Not Accepted | Not Accepted |
| Andorra | `AD` | Required | Not Accepted | Not Accepted |
| Angola | `AO` | Not Accepted | Not Accepted | Not Accepted |
| Anguilla | `AI` | Not Accepted | Not Accepted | Not Accepted |
| Antigua & Barbuda | `AG` | Not Accepted | Not Accepted | Not Accepted |
| Argentina | `AR` | Required | Required | Required |
| Armenia | `AM` | Required | Not Accepted | Not Accepted |
| Aruba | `AW` | Not Accepted | Not Accepted | Not Accepted |
| Australia | `AU` | Required | Required | Required |
| Austria | `AT` | Required | Not Accepted | Not Accepted |
| Azerbaijan | `AZ` | Required | Not Accepted | Not Accepted |
| Bahamas | `BS` | Not Accepted | Not Accepted | Not Accepted |
| Bahrain | `BH` | Required | Not Accepted | Not Accepted |
| Bangladesh | `BD` | Required | Not Accepted | Not Accepted |
| Barbados | `BB` | Required | Not Accepted | Not Accepted |
| Belarus | `BY` | Required | Not Accepted | Not Accepted |
| Belgium | `BE` | Required | Not Accepted | Not Accepted |
| Belize | `BZ` | Not Accepted | Not Accepted | Not Accepted |
| Benin | `BJ` | Not Accepted | Not Accepted | Not Accepted |
| Bermuda | `BM` | Required | Not Accepted | Not Accepted |
| Bhutan | `BT` | Required | Not Accepted | Not Accepted |
| Bolivia | `BO` | Not Accepted | Not Accepted | Not Accepted |
| Bosnia & Herzegovina | `BA` | Required | Not Accepted | Not Accepted |
| Botswana | `BW` | Required | Not Accepted | Not Accepted |
| Brazil | `BR` | Required | Required | Required |
| British Virgin Islands | `VG` | Required | Not Accepted | Not Accepted |
| Brunei | `BN` | Required | Not Accepted | Not Accepted |
| Bulgaria | `BG` | Required | Not Accepted | Not Accepted |
| Burkina Faso | `BF` | Not Accepted | Not Accepted | Not Accepted |
| Burundi | `BI` | Required | Not Accepted | Not Accepted |
| Cambodia | `KH` | Required | Not Accepted | Not Accepted |
| Cameroon | `CM` | Required | Not Accepted | Not Accepted |
| Canada | `CA` | Required | Required | Optional |
| Cape Verde | `CV` | Required | Not Accepted | Not Accepted |
| Caribbean Netherlands | `BQ` | Required | Not Accepted | Not Accepted |
| Cayman Islands | `KY` | Required | Not Accepted | Not Accepted |
| Central African Republic | `CF` | Required | Not Accepted | Not Accepted |
| Chad | `TD` | Not Accepted | Not Accepted | Not Accepted |
| Chile | `CL` | Required | Required | Required |
| China | `CN` | Required | Required | Required |
| Colombia | `CO` | Required | Required | Required |
| Comoros | `KM` | Required | Not Accepted | Not Accepted |
| Congo - Brazzaville | `CG` | Required | Not Accepted | Not Accepted |
| Cook Islands | `CK` | Required | Not Accepted | Not Accepted |
| Costa Rica | `CR` | Required | Not Accepted | Not Accepted |
| Croatia | `HR` | Required | Not Accepted | Not Accepted |
| Curaçao | `CW` | Not Accepted | Not Accepted | Not Accepted |
| Cyprus | `CY` | Required | Not Accepted | Not Accepted |
| Czech Republic | `CZ` | Required | Not Accepted | Required |
| Côte d’Ivoire | `CI` | Required | Not Accepted | Not Accepted |
| Denmark | `DK` | Required | Not Accepted | Required |
| Djibouti | `DJ` | Not Accepted | Not Accepted | Not Accepted |
| Dominica | `DM` | Required | Not Accepted | Not Accepted |
| Dominican Republic | `DO` | Required | Not Accepted | Not Accepted |
| Ecuador | `EC` | Required | Not Accepted | Not Accepted |
| Egypt | `EG` | Required | Required | Not Accepted |
| El Salvador | `SV` | Required | Not Accepted | Not Accepted |
| Eritrea | `ER` | Required | Not Accepted | Not Accepted |
| Estonia | `EE` | Required | Not Accepted | Not Accepted |
| Eswatini | `SZ` | Required | Not Accepted | Not Accepted |
| Ethiopia | `ET` | Required | Not Accepted | Not Accepted |
| Faroe Islands | `FO` | Required | Not Accepted | Not Accepted |
| Fiji | `FJ` | Not Accepted | Not Accepted | Not Accepted |
| Finland | `FI` | Required | Not Accepted | Required |
| France | `FR` | Required | Not Accepted | Not Accepted |
| French Polynesia | `PF` | Required | Not Accepted | Not Accepted |
| Gabon | `GA` | Required | Not Accepted | Not Accepted |
| Gambia | `GM` | Required | Not Accepted | Not Accepted |
| Georgia | `GE` | Required | Not Accepted | Not Accepted |
| Germany | `DE` | Required | Not Accepted | Not Accepted |
| Ghana | `GH` | Not Accepted | Not Accepted | Not Accepted |
| Gibraltar | `GI` | Required | Not Accepted | Not Accepted |
| Greece | `GR` | Required | Not Accepted | Not Accepted |
| Greenland | `GL` | Required | Not Accepted | Not Accepted |
| Grenada | `GD` | Required | Not Accepted | Not Accepted |
| Guatemala | `GT` | Required | Required | Not Accepted |
| Guernsey | `GG` | Required | Not Accepted | Not Accepted |
| Guinea | `GN` | Required | Not Accepted | Not Accepted |
| Guinea-Bissau | `GW` | Required | Not Accepted | Not Accepted |
| Guyana | `GY` | Required | Not Accepted | Not Accepted |
| Haiti | `HT` | Required | Not Accepted | Not Accepted |
| Honduras | `HN` | Required | Not Accepted | Not Accepted |
| Hong Kong | `HK` | Not Accepted | Required | Required |
| Hungary | `HU` | Required | Not Accepted | Not Accepted |
| Iceland | `IS` | Required | Not Accepted | Not Accepted |
| India | `IN` | Required | Required | Required |
| Indonesia | `ID` | Required | Required | Not Accepted |
| Iraq | `IQ` | Required | Not Accepted | Not Accepted |
| Ireland | `IE` | Required | Required | Not Accepted |
| Isle of Man | `IM` | Required | Not Accepted | Not Accepted |
| Israel | `IL` | Required | Not Accepted | Not Accepted |
| Italy | `IT` | Required | Required | Optional |
| Jamaica | `JM` | Not Accepted | Not Accepted | Not Accepted |
| Japan | `JP` | Required | Required | Optional |
| Jersey | `JE` | Required | Not Accepted | Not Accepted |
| Jordan | `JO` | Required | Not Accepted | Not Accepted |
| Kazakhstan | `KZ` | Required | Not Accepted | Not Accepted |
| Kenya | `KE` | Required | Not Accepted | Required |
| Kiribati | `KI` | Required | Not Accepted | Not Accepted |
| Kosovo | `XK` | Required | Not Accepted | Not Accepted |
| Kuwait | `KW` | Required | Not Accepted | Not Accepted |
| Kyrgyzstan | `KG` | Required | Not Accepted | Not Accepted |
| Laos | `LA` | Required | Not Accepted | Not Accepted |
| Latvia | `LV` | Required | Not Accepted | Not Accepted |
| Lebanon | `LB` | Required | Not Accepted | Not Accepted |
| Lesotho | `LS` | Required | Not Accepted | Not Accepted |
| Liberia | `LR` | Required | Not Accepted | Not Accepted |
| Liechtenstein | `LI` | Required | Not Accepted | Not Accepted |
| Lithuania | `LT` | Required | Not Accepted | Not Accepted |
| Luxembourg | `LU` | Required | Not Accepted | Not Accepted |
| Macao SAR China | `MO` | Required | Not Accepted | Not Accepted |
| Madagascar | `MG` | Required | Not Accepted | Not Accepted |
| Malawi | `MW` | Not Accepted | Not Accepted | Not Accepted |
| Malaysia | `MY` | Required | Required | Required |
| Maldives | `MV` | Required | Not Accepted | Not Accepted |
| Mali | `ML` | Not Accepted | Not Accepted | Not Accepted |
| Malta | `MT` | Required | Not Accepted | Not Accepted |
| Mauritania | `MR` | Required | Not Accepted | Not Accepted |
| Mauritius | `MU` | Required | Not Accepted | Not Accepted |
| Mexico | `MX` | Required | Required | Required |
| Moldova | `MD` | Required | Not Accepted | Not Accepted |
| Monaco | `MC` | Required | Not Accepted | Not Accepted |
| Mongolia | `MN` | Required | Not Accepted | Not Accepted |
| Montenegro | `ME` | Required | Not Accepted | Not Accepted |
| Montserrat | `MS` | Required | Not Accepted | Not Accepted |
| Morocco | `MA` | Required | Not Accepted | Not Accepted |
| Mozambique | `MZ` | Required | Not Accepted | Not Accepted |
| Myanmar (Burma) | `MM` | Required | Not Accepted | Not Accepted |
| Namibia | `NA` | Required | Not Accepted | Not Accepted |
| Nauru | `NR` | Required | Not Accepted | Not Accepted |
| Nepal | `NP` | Required | Not Accepted | Not Accepted |
| Netherlands | `NL` | Required | Not Accepted | Not Accepted |
| New Zealand | `NZ` | Required | Required | Optional |
| Nicaragua | `NI` | Required | Not Accepted | Not Accepted |
| Niger | `NE` | Required | Not Accepted | Not Accepted |
| Nigeria | `NG` | Required | Required | Required |
| Niue | `NU` | Required | Not Accepted | Not Accepted |
| North Macedonia | `MK` | Required | Not Accepted | Not Accepted |
| Norway | `NO` | Required | Not Accepted | Not Accepted |
| Oman | `OM` | Required | Not Accepted | Not Accepted |
| Pakistan | `PK` | Required | Not Accepted | Not Accepted |
| Palestinian Territories | `PS` | Required | Not Accepted | Not Accepted |
| Panama | `PA` | Not Accepted | Required | Not Accepted |
| Papua New Guinea | `PG` | Required | Not Accepted | Not Accepted |
| Paraguay | `PY` | Required | Not Accepted | Not Accepted |
| Peru | `PE` | Required | Required | Not Accepted |
| Philippines | `PH` | Required | Required | Optional |
| Poland | `PL` | Required | Not Accepted | Optional |
| Portugal | `PT` | Required | Required | Not Accepted |
| Qatar | `QA` | Not Accepted | Not Accepted | Not Accepted |
| Romania | `RO` | Required | Required | Not Accepted |
| Russia | `RU` | Required | Required | Not Accepted |
| Rwanda | `RW` | Required | Not Accepted | Not Accepted |
| Samoa | `WS` | Required | Not Accepted | Not Accepted |
| San Marino | `SM` | Required | Not Accepted | Not Accepted |
| Saudi Arabia | `SA` | Required | Not Accepted | Not Accepted |
| Senegal | `SN` | Required | Not Accepted | Not Accepted |
| Serbia | `RS` | Required | Not Accepted | Not Accepted |
| Seychelles | `SC` | Required | Not Accepted | Not Accepted |
| Sierra Leone | `SL` | Not Accepted | Not Accepted | Not Accepted |
| Singapore | `SG` | Required | Not Accepted | Required |
| Slovakia | `SK` | Required | Not Accepted | Not Accepted |
| Slovenia | `SI` | Required | Not Accepted | Not Accepted |
| Solomon Islands | `SB` | Required | Not Accepted | Not Accepted |
| Somalia | `SO` | Required | Not Accepted | Not Accepted |
| South Africa | `ZA` | Required | Required | Required |
| South Korea | `KR` | Required | Required | Not Accepted |
| South Sudan | `SS` | Not Accepted | Not Accepted | Not Accepted |
| Spain | `ES` | Required | Required | Optional |
| Sri Lanka | `LK` | Required | Not Accepted | Not Accepted |
| St. Kitts & Nevis | `KN` | Required | Not Accepted | Not Accepted |
| St. Lucia | `LC` | Required | Not Accepted | Not Accepted |
| St. Martin | `MF` | Required | Not Accepted | Not Accepted |
| St. Vincent & Grenadines | `VC` | Required | Not Accepted | Not Accepted |
| Sudan | `SD` | Required | Not Accepted | Not Accepted |
| Suriname | `SR` | Required | Not Accepted | Not Accepted |
| Sweden | `SE` | Required | Not Accepted | Required |
| Switzerland | `CH` | Required | Not Accepted | Not Accepted |
| São Tomé & Príncipe | `ST` | Required | Not Accepted | Not Accepted |
| Taiwan | `TW` | Required | Not Accepted | Not Accepted |
| Tajikistan | `TJ` | Required | Not Accepted | Not Accepted |
| Tanzania | `TZ` | Required | Not Accepted | Not Accepted |
| Thailand | `TH` | Required | Required | Not Accepted |
| Timor-Leste | `TL` | Required | Not Accepted | Not Accepted |
| Togo | `TG` | Not Accepted | Not Accepted | Not Accepted |
| Tonga | `TO` | Not Accepted | Not Accepted | Not Accepted |
| Trinidad & Tobago | `TT` | Not Accepted | Not Accepted | Not Accepted |
| Tunisia | `TN` | Required | Not Accepted | Not Accepted |
| Turkey | `TR` | Required | Not Accepted | Required |
| Turkmenistan | `TM` | Required | Not Accepted | Not Accepted |
| Turks & Caicos Islands | `TC` | Required | Not Accepted | Not Accepted |
| Tuvalu | `TV` | Not Accepted | Not Accepted | Not Accepted |
| Uganda | `UG` | Not Accepted | Not Accepted | Not Accepted |
| Ukraine | `UA` | Required | Not Accepted | Not Accepted |
| United Arab Emirates | `AE` | Not Accepted | Required | Not Accepted |
| United Kingdom | `GB` | Required | Not Accepted | Not Accepted |
| United States | `US` | Required | Required | Optional |
| Uruguay | `UY` | Required | Not Accepted | Not Accepted |
| Uzbekistan | `UZ` | Required | Not Accepted | Not Accepted |
| Vanuatu | `VU` | Not Accepted | Not Accepted | Not Accepted |
| Vatican City | `VA` | Required | Not Accepted | Not Accepted |
| Venezuela | `VE` | Required | Not Accepted | Not Accepted |
| Vietnam | `VN` | Required | Not Accepted | Not Accepted |
| Western Sahara | `EH` | Required | Not Accepted | Not Accepted |
| Yemen | `YE` | Not Accepted | Not Accepted | Not Accepted |
| Zambia | `ZM` | Required | Not Accepted | Not Accepted |
| Zimbabwe | `ZW` | Not Accepted | Not Accepted | Not Accepted |

---


# Identity Verification - Introduction to Identity Verification | Plaid Docs

Introduction to Identity Verification  
=======================================

#### Verify the identity of your users for global KYC and anti-fraud. 

Get started with Identity Verification

[API Reference](https://plaid.com/docs/api/products/identity-verification/index.html.md) [Request Access](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) [Quickstart](https://github.com/plaid/idv-quickstart) [Demo](https://plaid.coastdemo.com/share/6786ccc5a048a5f1cf748cb5?zoom=100)

#### Overview 

Plaid Identity Verification (IDV) lets you verify the identity of your customers and seamlessly stitches together verification methods. Using Identity Verification, you can verify identification documents, phone numbers, name, date of birth, ID numbers, addresses, and more. Identity Verification also integrates directly with [Monitor](https://plaid.com/docs/monitor/index.html.md) for an end-to-end verification and KYC solution.

(An image of "Plaid Link Identity Verification process showing steps: enter basic info, address, ID upload, selfie capture, and verification success.")

Plaid Identity Verification can also be used together with [Plaid Identity](https://plaid.com/docs/identity/index.html.md) in a single workflow to provide full identity verification and fraud reduction. Identity Verification is used to verify that the user of your app is the person they claim to be, while [Identity](https://plaid.com/docs/identity/index.html.md) is used to confirm that the ownership information on their linked bank or credit card account matches this verified identity. When used with Monitor, Identity Verification checks for the presence of a user on various watchlists and PEP lists.

Identity Verification can be used to verify end users in nearly 190 countries. To integrate with Identity Verification, your company must be based in the US, Canada, or UK.

[Watch video](https://www.youtube.com/watch?v=WyADMPl1R8w)

#### Identity Verification checks 

Plaid offers a variety of verification checks to choose from. You can combine multiple verification checks within a single Identity Verification template via the Workflow Management editor, and even run certain checks conditionally, such as only running a particular verification if another verification fails, or running different checks based on your user's country of origin.

For a more in-depth view of Identity Verification checks, including details on what each check verifies and how to handle failures, see [Identity Verification Manual](https://plaid.com/documents/idv-user-manual.pdf) . After running your selected checks, Identity Verification will also display a set of granular risk scores (email risk, phone risk, etc.) in the Dashboard for each session, along with an overall risk score, helping you to understand which factors contributed to the session passing or failing and which sessions have been identified as the highest risk.

When configuring your checks, it is typically recommended to start with the default templates and risk rules, then fine-tune them as needed based on your results.

##### Data Source Verification 

Data Source Verification (formerly known as Lightning Verification) verifies a user's name, address, date of birth, phone number, and ID number (such as SSN) against available records. These records are sourced from high-quality, trusted databases such as voter and driver registration records, property records, and credit bureau records. You can configure the level of matching required for each field in your template’s Identity Rules. The results of this check will be summarized in the `kyc_check` object in the API.

Note that certain end user segments, such as recent immigrants and end users aged 18-21, are less likely to pass data source verification, due to having a "thin file" (i.e., fewer data source records available to verify against). If these groups constitute a substantial portion of the audience you will be verifying, you may wish to enable Document Verification as a backup verification method.

##### Document Verification 

Document Verification prompts the user to upload an image of an identity document. Plaid will use anti-fraud checks to verify that the document appears to be legitimate and is unexpired. Plaid will also verify the date of birth and name on the document against the data provided by the user (other fields that may be present on the document, such as address or national ID number, will not be verified). You can review and configure which document types are supported for each country.

Document Verification can be used as a potential fallback for Data Source Verification (e.g. for verifying thin file customers). It can also be used as a primary method of verification, especially in countries where Data Source Verification is not supported.

##### Selfie Check 

When Selfie Check is enabled, the user will be asked to take a selfie on their mobile device as part of the verification process. Plaid will verify that the selfie submitted is a live video of a real human. If Document Verification is enabled, Selfie Check will also verify that the selfie matches the photo in the document.

If the user is on a non-mobile device, Plaid will display a QR code that they can use to perform the Selfie Check on mobile. They will resume the computer-based flow once the Selfie Check is complete. This handoff process is automatic and does not require any integration work on your part.

##### SMS Verification 

SMS Verification will verify a user's phone number by asking them to enter a code sent via SMS.

##### AML Screening 

If you're also using [Monitor](https://plaid.com/docs/monitor/index.html.md) , AML Screening allows you to screen a user against government watchlists during an IDV session by incorporating one of your Monitor screening programs into an IDV template.

##### Risk Check 

Plaid automatically runs anti-fraud checks in the background of a user’s verification session and summarizes the results into several categories. The data collected in each category is analyzed and assigned a risk level. Whether the overall risk check passes or fails is determined by the template’s Risk Rules, which you can configure. For more details on the risk check process, see [Anti-fraud monitoring](https://plaid.com/documents/idv-fraud-checks-deepdive.pdf) .

##### Checks not performed by Identity Verification 

Identity Verification is not a background check tool; it will not report whether an end user has a criminal record.

Identity Verification does not check citizenship or residency status, although you may be able to build your own business logic to determine this supported by Identity Verification results. For example, a valid passport from a country will typically indicate that the end user is a citizen of that country.

Identity Verification cannot be used to verify end users under the age of 18.

#### Identity Verification integration process 

[Watch video](https://www.youtube.com/watch?v=5EZwC5w6KCw)

Identity Verification is not available by default in the Sandbox environment. To obtain Sandbox access, [request full Production access for Identity Verification](https://dashboard.plaid.com/settings/team/products) , which will automatically grant Sandbox access, or, if you are not ready for Production access, [contact Sales](https://plaid.com/products/identity-verification/#contact-form) . To obtain Sandbox access for Identity Verification if you are already using another Plaid product, you can also contact your account manager or submit an [access request ticket](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) .

The steps below explain how to set up the standard Identity Verification flow. For details on other flow options, including the backend-only flow and hosted UI flow, see [Integration options for Identity Verification](https://plaid.com/docs/identity-verification/index.html.md#integration-options-for-identity-verification) .

Note that unlike other Plaid products, which are configured primarily via the API, most options for Identity Verification are configured on the web, via the [Template Editor](https://dashboard.plaid.com/identity_verification/templates) within the Identity Verification Dashboard. Detailed documentation on configuring Identity Verification templates is available via in-app help within the Template Editor. To request access to the Template Editor and Identity Verification Dashboard, contact your Plaid Account Manager, or file a [Product Access request](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

1.  Visit the [Plaid Dashboard](https://dashboard.plaid.com/) and select **Identity Verification** from the left sidebar. If you don't see this option, you may need to talk to your Plaid Account Manager and ask them to enable this product for you, or file a [Product access request](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .
2.  Select or create the template you want to use, click the **Integration** button, and copy the `template_id`.
    *   (Optional) If you plan to integrate with [Monitor](https://plaid.com/docs/monitor/index.html.md) , make sure to enable the **AML Screening** option and select the appropriate Monitor program within the IDV template editor.
3.  (Optional) Call [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) if you already have information about your user that you can fill out on their behalf. See [pre-populating user information](https://plaid.com/docs/identity-verification/index.html.md#streamlining-link-by-pre-populating-user-information-hybrid-link-flow) for more details.
4.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following:
    *   For `identity_verification.template_id`, use the `template_id` you copied in step 2.
    *   For `products`, use `["identity_verification"]`. Identity Verification is mutually exclusive with other products.
    *   Provide `user.client_user_id` and optionally `user.email_address`. See below for details on these fields.
5.  On your web or mobile client, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
6.  When the user has successfully completed the client-side Link flow, you will receive an [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback and be able to review the session in the dashboard. The `onSuccess` callback will return a Link session ID that can be used as the `identity_verification_id` in the next step. Unlike some other Plaid products, Identity Verification will not return a public token in `onSuccess`.
7.  To retrieve the status of your user's verification attempt, make a call to [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , passing in the verification session ID. You can retrieve this session ID from the metadata in the Link callbacks, from the [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) response, or from the [Identity Verification webhooks](https://plaid.com/docs/identity-verification/webhooks/index.html.md) that Plaid sends during the process.
8.  You can retrieve a list of all of your user's verification attempts by making a call to [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) , passing in the `client_user_id` and the `template_id`.

##### Events and callbacks 

You can optionally track the progress of users through the Link flow via client-side callbacks and events. For more information, see [Link callbacks](https://plaid.com/docs/identity-verification/link/index.html.md) .

##### Mobile support 

Identity Verification is fully supported by Plaid's mobile SDKs. Because the end user may need to use the camera during the Identity Verification flow, your app must request certain permissions in order to fully support Identity Verification flows on mobile. For more details, see the documentation for the [Android](https://plaid.com/docs/link/android/index.html.md#enable-camera-support-identity-verification-only) and [iOS](https://plaid.com/docs/link/ios/index.html.md#camera-support-identity-verification-only) SDKs.

##### Client User Id 

The mandatory `client_user_id` field should be a unique and persistent identifier for your customer, such as the `id` field on your users table.

Identity Verification intelligently handles sessions being started with the same `client_user_id` multiple times. If your customer starts a Link session, closes it, reopens it, and reopens your Link integration, their session will resume from where they left off. Likewise, if your customer has completed their Link session in the past (by either failing verification or passing), Plaid will not serve them another session unless you've manually authorized another attempt from the dashboard or made a call to [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) .

Plaid indexes the `client_user_id` you provide, allowing you to look up users using your internal id.

If you do not want to expose your internal id to Plaid directly, you can symmetrically encrypt the identifier with a secret key that only your servers know.

##### Supplementing with email 

During [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) , Identity Verification accepts `email_address` as an optional additional parameter. While the field is optional, we highly recommend providing it. Identity Verification will include the user's email in the Link session and perform a number of anti-fraud related checks, including analyzing social networks, abusive emails, and email address trustworthiness.

#### Integration options for Identity Verification 

Identity Verification offers several options for streamlined flows.

The Plaid Link flow is designed to collect high quality user data, through an optimized UI and input validation. If you are bypassing the Link data entry UI and are instead passing user data via API, be sure you are providing data in the correct format expected by the API and have taken steps to avoid issues such as typos or incorrect data entry (e.g. an end user entering a date of birth using a different date format than your app expects). Providing unvalidated or malformatted data via the API will result in degraded success rates for Data Source Verification.

For more details on data formatting requirements and validation rules you can use for input you collect, see [input validation](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md) .

##### Streamlining Link by pre-populating user information (hybrid Link flow) 

If you already know some information about your user (such as their name, phone number, or address), you can simplify the verification process by making a call to [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) , passing in any information you know about your user, including their `client_user_id`. When you open up a Link session against this same `client_user_id`, Identity Verification can make use of the information that you passed in. Any fields or screens requesting information you already provided will be skipped (not shown) in the UI. This means that an end user will not be able to override or change pre-populated user information during the Link flow. For data format specifications, see [Input Validation](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md) .

##### Data Source Checks without UI (backend flow) 

If you have already obtained a user's information and their consent to share it with Plaid, and do not need interactive capabilities such as Document Check, Selfie Check, or SMS verification, you can bypass the Identity Verification UI entirely and run an entirely programmatic verification:

1.  Create a template that requires only Data Source (KYC) check and does not use SMS verification.
2.  Call [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) with all the user data required by this template and `gave_consent: true`.
3.  Wait for the `STATUS_UPDATED` webhook to fire for the `id` returned by [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . Alternatively, you can poll [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) with this id until the `status` is no longer `active`.
4.  Call [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) with the id returned by [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) to retrieve the status of the verification.

When using the backend-only flow, the Network Risk, Device and IP Address, and Behavioral Analytics checks will be unavailable, as they require client-side input.

##### Verification links (hosted flow) 

Identity Verification offers the option to generate Plaid-hosted verification links. These links can be used in scenarios where your user signed up for your service outside of an app or website -- for example if a user is opening a bank account or applying for a loan in person at a brick-and-mortar retail location. To generate a verification link, click **Create verification** from the Identity Verification template view in the dashboard. Alternatively, you can call [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) with `is_shareable: true`; a verification link will be returned in the `shareable_url` field of the response. Once you have shared the verification link, the user can open the link and complete the verification on their phone or other device.

Note that verification links are intended to be sent directly to your users; hosting verification links via iframe will be blocked.

##### Auto-fill 

When auto-fill is enabled, Plaid will use the user's phone number and date of birth to attempt to auto-fill other fields. The user will be asked to confirm their auto-filled information is accurate before submitting. Auto-fill can only be enabled when using SMS Verification and Data Source Verification and is only available for US verifications. Enabling auto-fill when possible is strongly recommended, as it has a substantial positive impact on Link flow conversion.

##### Retries 

If you want to give a user another attempt to verify their identity -- for example, if they failed verification due to a typo -- you can issue them a retry. This can be done from the dashboard when reviewing a verification by clicking **Request Retry** and selecting the steps to include, or via API by calling [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) with their `client_user_id`, `template_id`, and the `strategy` you want to use.

Retries can be issued from any verification check. Any steps included in the retry will be reset and cleared of any PII entered by the user or passed via API in previous verification attempts. Data Source data can be passed programmatically for a retry by calling [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) and passing the user’s data in the `user` object. [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) should only be used to create an initial session for users who have never been verified before.

Each retry will generate a new `session_id`, with the same `client_user_id` and `template_id` used in the original session. Retries will use the most recent version of the template, which may be different from the version used in the original verification session. Retries are billed at the same rate as regular sessions.

While allowing retries is useful to help users who have legitimately made an error, allowing too many retry attempts can attract fraud. We recommend starting with no more than two retry attempts allowed per user.

###### Step-up verification 

Retries can also be used as part of a "step-up" verification process. To use retries in this way, send the user through Identity Verification, and examine the results via the Dashboard or [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) . If their risk results meet your criteria for requiring a step-up, you can issue a retry using a different `template_id`. For example, you might send users through a template that doesn't require documentary verification, but if their risk check failed, you might step them up to a new template that does require documentary verification.

##### Financial Account Matching 

If you are a customer of [Identity](https://plaid.com/docs/identity/index.html.md) or [Assets](https://plaid.com/docs/assets/index.html.md) , you can seamlessly compare a user's financial accounts with their Identity Verification profile. When a user verifies their identity and links their accounts with Plaid, we detect if they are linking a bank account that belongs to them. In the Plaid Dashboard, you’ll see "match" scores against the account owner’s name, email, phone number, and address.

To turn on this feature, you will need to enable it in the template editor and call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) , [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , or [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) with the same `client_user_id` that was used for Identity Verification. Financial Account Matching will only run if the `client_user_id` is associated with a successful (passed) Identity Verification session.

##### Fraud labeling 

Identity Verification offers the ability to flag a session as fraudulent via the Dashboard. Labeling fraudulent sessions will allow Identity Verification to refine its fraud model, resulting in higher fraud detection accuracy for your integration.

#### Supported languages 

Identity Verification currently supports flows in English, French, Spanish, Japanese, and Portuguese. Link will attempt to auto-detect the correct language based on the user's browser settings. Users can also manually change the language of their session through a dropdown in the Link UI. Unlike other Plaid products, Identity Verification does not use the language setting in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

#### Supported countries 

Identity Verification supports end users in all countries, with the exception of North Korea, Libya, DR Congo, Iran, Cuba, and Syria.

Data Source checks are available in the following countries: Argentina, Australia, Austria, Belgium, Brazil, Canada, Chile, China, Colombia, Czechia, Denmark, Finland, France, Germany, Gibraltar, Hong Kong, India, Ireland, Italy, Japan, Kenya, Luxembourg, Malaysia, Mexico, Netherlands, New Zealand, Nigeria, Norway, Philippines, Poland, Portugal, Singapore, Slovakia, Spain, Sweden, Switzerland, Turkey, United Kingdom, United States.

Note that Data Source Verification success rates vary by country. For more details on a specific country, contact your account manager. If you are running Data Source Verification checks on users outside the US, you may wish to use Documentary Verification as a fallback method in order to increase verification success rates.

Selfie Checks and Documentary Verification are available in all supported countries.

#### Data retention and redaction 

Identity Verification will retain data about user sessions as long as you maintain an active Identity Verification contract with Plaid. To request that user personally identifiable information (PII) be redacted on a rolling basis, such as after 90 days, contact support or your Plaid Account Manager to request a custom retention period. Redaction is permanent, and once you have set up a custom retention period, you cannot regain access to redacted data. You can also redact data on an ad-hoc basis via the Dashboard.

You can export data relating to user sessions via the Dashboard or the API. If you end your contract with Plaid, you will lose access to the Identity Verification Dashboard and API, including access to information about previous sessions. If your use case requires that you retain user session data after your contract ends, export the data prior to the end of your contract.

#### Testing Identity Verification 

For more information about testing Identity Verification in Sandbox, see [Testing Identity Verification](https://plaid.com/docs/identity-verification/testing/index.html.md) .

#### Sample app and additional resources 

For a sample integration, see the [Identity Verification Quickstart](https://github.com/plaid/idv-quickstart) on GitHub.

The PDF resources below provide an in-depth view of IDV integration and configuration options. Note that they are not updated as frequently as the docs and may not reflect the most recent updates to Identity Verification capabilities.

*   [Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf) : A detailed, step-by-step walkthrough for integrating and configuring Identity Verification and Monitor.
*   [Identity Verification and Monitor no-code guide](https://plaid.com/documents/idv-monitor-no-code-testing-guide.pdf) : A walkthrough of setting up a Identity Verification and Monitor integration with no code, using the [verification links](https://plaid.com/docs/identity-verification/index.html.md#verification-links-hosted-flow) option. This demo flow can help you quickly work with Identity Verification and Monitor and try out the end-user and admin experiences.
*   [Identity Verification Manual](https://plaid.com/documents/idv-user-manual.pdf) : Shows the different verification checks available, what each one checks, and how to handle failures.
*   [Anti-fraud monitoring](https://plaid.com/documents/idv-fraud-checks-deepdive.pdf) : Shows details on how risk checks are performed.

#### Identity Verification pricing 

Identity Verification has a base fee for every verification attempted, as well as separate fees for Data Source verification, Selfie checks, and Document checks. For more details, see the [Identity Verification fee model](https://plaid.com/docs/account/billing/index.html.md#identity-verification-fee-model) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) .

#### Next steps 

To learn more about building with Identity Verification, see the [Identity Verification API Reference](https://plaid.com/docs/api/products/identity-verification/index.html.md) .

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Identity Verification - Link callbacks | Plaid Docs

Link callbacks 
===============

#### Guide to using Link callbacks in your integration 

After integrating Identity Verification using Link, you can use Link’s client-side callbacks to see how your users are progressing through the flow. Note that you will not be able to access these if you use the Plaid-hosted flow with shareable links.

[onSuccess](https://plaid.com/docs/link/web/index.html.md#link-web-create-onSuccess) will fire when a user has successfully completed the Link flow. The `link_session_id` returned by `onSuccess` can be passed to [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) in the `identity_verification_id` field to retrieve data on the verification. Note that receiving `onSuccess` simply means that the user completed the Identity Verification flow, not that their identity was verified. A completed session in which a user fails Identity Verification will still result in `onSuccess`.

[onExit](https://plaid.com/docs/link/web/index.html.md#link-web-create-onExit) will fire when a user exits a session without finishing all required steps. If you receive this event, you may want to provide an option for the user to restart the Link flow, and/or provide guidance on manually performing KYC.

[onEvent](https://plaid.com/docs/link/web/index.html.md#link-web-create-onEvent) will fire at certain points throughout the IDV flow with updates on the user’s progress at each point. For each step, Plaid will send an [IDENTITY\_VERIFICATION\_START\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-START-STEP) event as well as a [IDENTITY\_VERIFICATION\_PASS\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PASS-STEP) or [IDENTITY\_VERIFICATION\_FAIL\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-FAIL-STEP) event based on the outcome of the step. Each step will also have an associated `view_name`. The possible view names include: [ACCEPT\_TOS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-ACCEPT-TOS) , [VERIFY\_SMS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-VERIFY-SMS) ,[KYC\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-KYC-CHECK) , [DOCUMENTARY\_VERIFICATION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-DOCUMENTARY-VERIFICATION) , [RISK\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-RISK-CHECK) , and [SELFIE\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELFIE-CHECK) .

For each session, Plaid will also inform you of the outcome of the session by sending an [IDENTITY\_VERIFICATION\_PASS\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PASS-SESSION) or [IDENTITY\_VERIFICATION\_FAIL\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-FAIL-SESSION) event based on the outcome of the session.

Note that, aside from `IDENTITY_VERIFICATION_PASS_SESSION` and `IDENTITY_VERIFICATION_FAIL_SESSION`, the sequence of view names and `onEvent` events are subject to change without notice, as Plaid adds additional functionality and makes improvements to flows. You should treat view names as informational and not rely on them for critical business logic.

---


# Identity Verification - Metrics and reporting | Plaid Docs

Generating metrics 
===================

#### Generating metrics for Identity Verification 

You can view the status of any Identity Verification session in the Dashboard. To obtain aggregated data such as the percentage of sessions that were completed or the percentage that passed verification vs. were rejected, you will need to use the API to generate the data.

#### Conversion and success rates 

The _conversion rate_ is defined as the percentage of sessions begun that were completed, regardless of whether the user passed or failed verification.

The _success rate_ is defined as the percentage of completed sessions that resulted in the user passing verification.

#### Calculating success rates 

The most comprehensive way to measure overall success rates is to use [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , since it includes backend-only sessions, sessions generated using shareable links, and manual overrides after the session is completed.

If the status is `success`, the verification succeeded.

If the status is `failed` or `pending review`, the verification did not succeed.

The success rate is the number of sessions with the `success` status divided by the total of all sessions with the `success`, `failed`, or `pending review` status.

Sessions with a status other than `success`, `failed`, or `pending review` should be discarded for the purpose of calculating overall success rates, since they represent sessions that were not completed.

#### Calculating conversion rates 

If you want to measure the conversion rate, you can use the `onEvent` callback. A session is started if you receive the `IDENTITY_VERIFICATION_START_STEP` event. It was completed if you receive either the `IDENTITY_VERIFICATION_PASS_SESSION` or `IDENTITY_VERIFICATION_FAIL_SESSION` event, and it was successful only if you receive the `IDENTITY_VERIFICATION_PASS_SESSION`. To correlate different events with the same Link session, use the `link_session_id`. For more details, see [Link callbacks](https://plaid.com/docs/identity-verification/link/index.html.md) .

For Identity Verification, `onEvent` callback information is not available via the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint.

Alternatively, you can calculate conversion using [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) . The conversion rate is the number of sessions with a status of `success`, `failed`, or `pending review` divided by the total number of unique identity verification IDs. Because this metric includes sessions where the result was manually overridden, as well as backend-only sessions, it will provide different results from Link-based conversion metrics, especially if you use a combination of backend-based sessions and Link-based sessions. Whether it makes more sense to report on overall conversion or Link-based conversion will depend on your use case.

---


# Identity Verification - Testing in Sandbox | Plaid Docs

Testing in Sandbox 
===================

#### Test values and options for Identity Verification 

Identity Verification is not available by default in the Sandbox environment. To obtain Sandbox access, [request full Production access for Identity Verification](https://dashboard.plaid.com/settings/team/products) , which will automatically grant Sandbox access, or [contact Sales](https://plaid.com/products/identity-verification/#contact-form) . To obtain Sandbox access for Identity Verification if you are already using another Plaid product, you can also contact your account manager or submit an [access request ticket](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) .

#### Sandbox users for Identity Verification 

##### Primary test user (Leslie Knope) 

In Sandbox mode, Identity Verification accepts the fixed set of inputs below in order to result in successful Data Source and Document Verification checks.

| Form Field | Test Value |
| --- | --- |
| Mobile number | +1 234-567-8909 |
| First name | Leslie |
| Last name | Knope |
| Verification code | 11111 |
| Address | 123 Main St. |
| City | Pawnee |
| State | Indiana |
| ZIP code | 46001 |
| Month | January |
| Day | 18 |
| Year | 1975 |
| SSN | 123-45-6788 or 123-45-6789 |

##### Custom test users 

For US verifications, Plaid supports importing custom test users from your organization into Sandbox, allowing you to test your own sets of PII to result in successful Data Source and Document Verification checks. To learn more about creating custom test users for Identity Verification, contact your Plaid Account Manager.

#### Identity verification behavior in Sandbox 

##### Data Source checks 

Data Source checks in Sandbox will be compared against the information above. To simulate different test cases and results, you can adjust your Data Source input at the attribute level (e.g. an incorrect birthdate), and set up different Identity Rules to simulate different verification results.

##### Document checks 

Documents uploaded in Sandbox will always be interpreted as genuine (not fake) documents reflecting the name and date of birth matching the Leslie Knope test user. Document check will pass if the data provided in the Data Source check matches this name and date of birth, and will fail otherwise.

Users have three attempts to pass the Document check, so the status will not be updated in the Dashboard to `failed` until you have provided mismatching data three times.

##### Selfie checks 

Selfie checks will not be run in Sandbox mode, even if they are enabled in your template.

##### AML Screening 

In Sandbox, Monitor screens against a real-world dataset, so the Sandbox user will not return any screening hits. For more information, including example data you can use to trigger screening hits, see [Testing Monitor](https://plaid.com/docs/monitor/index.html.md#testing-monitor) .

##### Risk Check 

The risk check is fully functional in Sandbox. It’s common to trigger high risk scores when testing. For more information and advice, see [Risk rules for testing](https://plaid.com/docs/identity-verification/testing/index.html.md#risk-rules-for-testing) .

##### Auto-fill 

Auto-fill behavior is fully functional in Sandbox.

##### Financial Account Matching 

Financial Account Matching is fully functional in Sandbox. If you want to change the Identity data that is being compared to the Identity Verification session, see [how to create Sandbox test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) .

#### Risk rules for testing 

Many common testing behaviors (e.g. attempting to enter the Identity Verification flow repeatedly on the same device using different credentials) may be flagged as risky behavior and cause your verification attempt to fail. For testing purposes, you can temporarily set the Acceptable Risk Level for any checks you are failing (typically Network Risk and Device Risk) to **High**, under the **Rulesets -> Risk Rules** section of the template editor. Make sure to set the Acceptable Risk Level back to your desired setting before launching in Production.

If you want to force a check to fail in Sandbox, an easy way to do this is to set Acceptable Risk Level for the Network Risk and Device Risk fields to **Low**. Checks will begin failing after your first few attempts.

#### Triggering specific test outcomes 

Using the rules above, it is easy to create the outcome of passing both Data Source checks and Document checks, or of failing both checks. If you need to simulate specific combinations of pass / fail (passing one check but not the other), you can use the guides below.

##### Data Source check passes, Document Verification check fails 

1.  Set up your template to always be enabled for Data Source checks and Document Checks.
2.  Set up your template to not require a match or partial match on name or date of birth.
3.  Enter Leslie Knope's correct test data for the address, SSN, and phone number fields.
4.  Enter incorrect data for the name and date of birth fields.

If you would like this test to also trigger a Monitor hit, you can use the name and date of birth of a sanctioned individual. For examples, see [Monitor test data](https://plaid.com/docs/monitor/index.html.md#testing-monitor) .

##### Data Source check fails, Document Verification check passes 

1.  Set up your template to be enabled for Data Source checks, with Document checks as a fallback.
2.  Set up your template to require a match for address, SSN, and phone number fields.
3.  Enter Leslie Knope's correct test data for the name and date of birth fields.
4.  Enter incorrect data for the address, SSN, and phone number fields.

#### Testing Financial Account Matching 

1.  Create a template with Financial Account Matching enabled.
2.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `identity_verification` in the `products` array. Make sure to save the `client_user_id` you are using with this call, as you will need it later.
3.  Launch Link and complete the Identity Verification session, entering Leslie Knope's correct test data.
4.  See the [Sandbox custom user repo](https://github.com/plaid/sandbox-custom-users/tree/main) for instructions on configuring custom Sandbox users and create a custom user using the [Financial Account Matching custom user data](https://github.com/plaid/sandbox-custom-users/blob/main/identity/leslie_knope_financial_account_matching.json) from that repo.
5.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `identity` (or `assets`, for underwriting use cases) in the `products` array and the same `client_user_id` as was used in the first step, and launch a Link session.
6.  Use the custom user you created above to log in to Link, then call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the public token for an access token.
7.  Call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) or [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) (or [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) , if using `assets` instead of `identity`) on the access token.
8.  Check the Identity Verification session in the Dashboard. You should see the linked account and a successful match in the Financial Account Matching section.

---


# Identity Verification - Webhooks | Plaid Docs

Webhooks 
=========

#### Subscribe to events and get real-time alerts for changes 

Once you have Link with Identity Verification embedded in your app, you should be able to complete an entire session and review it in the dashboard.

To complete your integration, you need to add a webhook receiver endpoint to your application.

To add a webhook, visit the [dashboard webhook configuration page](https://dashboard.plaid.com/developers/webhooks) and click **New Webhook**. Note that this is the only setting used to configure Identity Verification webhook receivers; webhook URLs set via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) will not be used.

You can select which events you want to subscribe to. For Identity Verification, there are three events:

*   [STEP\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#step_updated)
*   [STATUS\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#status_updated)
*   [RETRIED](https://plaid.com/docs/api/products/identity-verification/index.html.md#retried)

Enter your webhook receiver endpoint for the webhook you wish to subscribe to and click **Save**. Plaid will now send an HTTP POST request to the webhook receiver endpoint every time the event occurs, in both the Sandbox and Production environments. If multiple webhook receiver endpoints are configured for an Identity Verification event, webhooks will be sent to all the configured endpoints.

#### Event ordering 

Identity Verification does not guarantee that webhooks will be delivered in any particular order. For example, while the logical ordering of webhooks for a Identity Verification session might look like this:

1.  `STEP_UPDATED` The user has started the Identity Verification session and is on the first step
2.  `STEP_UPDATED`
3.  `STATUS_UPDATED` The user has reached a terminal state for their session
4.  `RETRIED` A retry has been requested for this user, either via the dashboard or via API
5.  `STEP_UPDATED`
6.  `STEP_UPDATED`
7.  `STATUS_UPDATED` The retry has been completed

you should be prepared to handle these events in any delivery order. For example, consider whether your application will properly handle:

*   A `STEP_UPDATED` event being delivered after a `STATUS_UPDATED` event.
*   A `STEP_UPDATED` event being delivered before an associated `RETRIED`

In order to properly handle webhook events being delivered out of order, your application should lookup the user's associated session(s) via the [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) API.

#### Webhook Reference 

For full webhook information, refer to the [API Documentation](https://plaid.com/docs/api/products/identity-verification/index.html.md) .

---


# Identity - Add Identity to your app | Plaid Docs

Add Identity to your app 
=========================

#### Use Identity to verify user data 

In this guide, we'll start from scratch and walk through how to use [Identity](https://plaid.com/docs/api/products/identity/index.html.md) to retrieve identity data. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Matching identity data](https://plaid.com/docs/identity/add-to-app/index.html.md#matching-identity-data) (for [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) ) or [Fetching identity data](https://plaid.com/docs/identity/add-to-app/index.html.md#fetching-identity-data) (for [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) ).

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace `PLAID_CLIENT_ID` and `PLAID_SECRET` with your own keys, which you can obtain from the [Dashboard](https://dashboard.plaid.com/developers/keys) . These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.

##### Create a link\_token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['identity'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API.

#### Matching Identity data 

To match Identity data, call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) .

If you are using [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md) , you can automatically match data from the linked account against data collected during the Identity Verification flow. To enable this setting, from the Identity Verification section of the Dashboard, access the template editor and on the "Setup" pane of the template, check the box under the "Financial Account Matching" header. If this option is selected, you should call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) with only an `access_token` to obtain match scores.

If you are not using [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md) , you will need to send the identity information that you have on file and would like to match against, such as name, phone number, and address, as part of your call to [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) .

```javascript
const request = {
  access_token: accessToken,
  // Omit user object if using using Identity Verification / Financial Account Matching
  user: {
    legal_name: 'Jane Smith',
    phone_number: '+14155552671',
    email_address: 'jane.smith@example.com',
    address: {
      street: '500 Market St',
      city: 'San Francisco',
      region: 'CA',
      postal_code: '94105',
      country: 'US',
    },
  },
};


try {
  const response = await plaidClient.identityMatch(request);
  const accounts = response.data.accounts;
  for (const account of accounts) {
    const legalNameScore = account.legal_name?.score;
    const phoneScore = account.phone_number?.score;
    const emailScore = account.email_address?.score;
    const addressScore = account.address?.score;
  }
} catch (error) {
  // handle error
}
```

The call to [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) will return a match score for each field that was evaluated. Typically, your threshold to accept the field as a match should be set to at least 70. For more details, see the [match score table](https://plaid.com/docs/identity/index.html.md#sample-identity-match-data) .

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": null,
        "current": null,
        "iso_currency_code": null,
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "legal_name": {
        "score": 90,
        "is_nickname_match": true,
        "is_first_name_or_last_name_match": true,
        "is_business_name_detected": false
      },
      "phone_number": {
        "score": 100
      },
      "email_address": {
        "score": 100
      },
      "address": {
        "score": 100,
        "is_postal_code_match": true
      },
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "balances": {
        "available": null,
        "current": null,
        "iso_currency_code": null,
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "1111",
      "name": "Plaid Saving",
      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
      "legal_name": {
        "score": 30,
        "is_first_name_or_last_name_match": false
      },
      "phone_number": {
        "score": 100
      },
      "email_address": null,
      "address": {
        "score": 100,
        "is_postal_code_match": true
      },
      "subtype": "savings",
      "type": "depository"
    }
  ...
}
```

#### Fetching Identity data 

If you are not using Identity Match, call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) to obtain Identity data. You will need to implement your own matching algorithm to determine whether the data returned matches the information that you have on file about the user. For more detailed information on the schema returned, see [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { IdentityGetRequest } = require('plaid');


// Pull Identity data for an Item
const request: IdentityGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.identityGet(request);
  const identities = response.data.accounts.flatMap(
    (account) => account.owners,
  );
} catch (error) {
  // handle error
}
```

Example response data is below.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "owners": [
        {
          "addresses": [
            {
              "data": {
                "city": "Malakoff",
                "country": "US",
                "postal_code": "14236",
                "region": "NY",
                "street": "2992 Cameron Road"
              },
              "primary": true
            },
            {
              "data": {
                "city": "San Matias",
                "country": "US",
                "postal_code": "93405-2255",
                "region": "CA",
                "street": "2493 Leisure Lane"
              },
              "primary": false
            }
          ],
          "emails": [
            {
              "data": "accountholder0@example.com",
              "primary": true,
              "type": "primary"
            },
            {
              "data": "accountholder1@example.com",
              "primary": false,
              "type": "secondary"
            }
          ],
          "names": ["Alberta Bobbeth Charleson"],
          "phone_numbers": [
            {
              "data": "1112223333",
              "primary": false,
              "type": "home"
            },
            {
              "data": "1112224444",
              "primary": false,
              "type": "work"
            },
            {
              "data": "1112225555",
              "primary": false,
              "type": "mobile1"
            }
          ]
        }
      ],
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "item": {
    "available_products": ["balance", "credit_details", "investments"],
    "billed_products": [
      "assets",
      "auth",
      "identity",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "3nARps6TOYtbACO"
}
```

#### Tutorial and example code in Plaid Pattern 

For a real-life example of an app that incorporates Identity, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Identity data in order verify identity prior to a funds transfer. The Identity code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L116) .

For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Identity - Identity Document Upload | Plaid Docs

Identity Document Upload 
=========================

#### Learn about statement upload-based account ownership verification 

#### Overview 

In order to provide the user an additional way to verify their account ownership, Identity Document Upload can be used to upload a bank statement, verify that statement belongs to the account in question, and verify the ownership information on the statement. This feature is intended primarily for use with Items created via loginless Auth flows, such as Same-Day Micro-deposits, Instant Micro-deposits, or Database Insights.

Identity Document Upload is available as an add-on to Identity. For pricing details, and to request access to Identity Document Upload, contact your Plaid Account Manager or Sales.

To detect potential document fraud or document tampering during the Identity Document Upload flow, you can use the optional Fraud Risk feature, which scans for over two dozen different fraud signals in categories such as visual evidence of tampering, suspicious metadata, inconsistent contents, and similarity to known fraudulent documents.

#### Implementation 

To use Document Upload, you will first create the Item with another product such as Auth or Transfer. Then, run Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) with the following parameters (in addition to the required fields):

*   The `products` array set to `["identity"]`.
*   The `identity.account_ids` array should contain the `account_id` of the account to verify. Currently, only one `account_id` can be specified.
*   `identity.is_document_upload` should be set to `true`.
*   (Optional) to enable Fraud Risk, set `identity.parsing_configs` to `["ocr", "risk_signals"]`

```bash
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "client_name": "Insert Client name here",
  "products": ["identity"],
  "access_token": "Insert access token here",
  "identity": 
    {
      "is_document_upload": true, 
      "account_ids": ["ZXEbW7Rkr9iv1qj8abebU1KDJlkexgSgrLAod"], 
      "parsing_configs": ["ocr", "risk_signals"]
    },
  "country_codes": ["US"],
  "language": "en",
  "user": {
    "client_user_id": "unique_user_id"
  }
}'
```

During update mode, the end user will be prompted to upload a bank statement. After the statement has been uploaded and processed, Plaid will send an `IDENTITY: DOCUMENT_UPDATE_AVAILABLE` webhook. A `"document_status": "OCR_PROCESSING_COMPLETE"` field in the webhook body indicates that the statement was successfully parsed.

If the parsing is successful, you can call [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) , which will return the identity data parsed from the document in the same format as [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) . This endpoint will also return a `documents` array -- for any given document in the array, if the `metadata.is_account_number_match` field is `true`, Plaid has verified that the account number on the document matches the account number known to Plaid. If it is `false`, the document does not substantiate the end user's ownership of the account.

```json
"documents": [
  {
      "document_id": "1d107b7f-91fe-44c8-b8e9-325494addf5d",
      "metadata": {
          "document_type": "BANK_STATEMENT",
          "is_account_number_match": true,
          "last_updated": "2024-01-29T08:06:46Z",
          "uploaded_at": "2024-01-29T08:06:46Z"
      },
      "risk_insights": {
          "risk_signals": [
              {
                  "has_fraud_risk": true,
                  "page_number": 0,
                  "signal_description": "Creation date and modification date do not match",
                  "type": "METADATA_DATES_OUTSIDE_WINDOW"
              },
              {
                  "has_fraud_risk": true,
                  "page_number": 0,
                  "signal_description": "Adobe Acrobat",
                  "type": "SOFTWARE_BLACKLIST"
              }
          ],
          "risk_summary": {
              "risk_score": 100
          }
      }
  }
],
```

If Fraud Risk was enabled, the `document` object will contain a `risk_insights` object, including details about potential risks detected in the uploaded document. The `risk_insights.risk_summary.risk_score` field will contain a score summarizing the risk of the document. If the score is 80 or higher, we recommend treating the account identity as unverified and potentially high risk and sending the user through a manual verification flow.

##### Testing Identity Document Upload 

In the Sandbox, Plaid will not parse the uploaded bank statement and will instead return pre-populated test user data. Because of this, Sandbox will proceed much faster than Production; you should make sure your app can handle the asynchronous behavior of Production, in which the user's statement will be verified after they have completed Link, rather than during the Link session.

In Sandbox, you must provide a valid webhook URI in order to upload documents.

---


# Identity - Introduction to Identity | Plaid Docs

Introduction to Identity  
==========================

#### Verify users' account ownership and reduce fraud with the Identity product. 

Get started with Identity

[API Reference](https://plaid.com/docs/api/products/identity/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md)

#### Overview 

Plaid's Identity product helps you verify users' identities by accessing information on file with their financial institution. Using Identity, you can access a user's phone number, email address, mailing address, and name. This can be used to fight fraud by verifying that the linked financial institution account is owned by the same user who created an account with you.

[Prefer to learn by watching? Get an overview of how Identity works in just 3 minutes!](https://www.youtube.com/watch?v=ILSSdpgGBaU)

Plaid provides two endpoints for Identity:

*   [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) retrieves the user's name and contact information from their financial institution
*   [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) allows you to provide a name and contact information for a user and returns a set of match scores indicating how well that information matches the information on file with their financial institution, simplifying the process of using identity data for account ownership verification.

Both endpoints can be used to reduce fraud, improve user onboarding and conversion, and to complement Know Your Customer (KYC) compliance checks.

Identity can be used to verify all major account types supported by Plaid, including checking and savings accounts, credit cards, brokerage accounts, and loans. Identity coverage can be used to verify an account before initiating an ACH transaction: 97% of Items initialized with [Auth](https://plaid.com/docs/auth/index.html.md) provide Identity data as well.

Depending on your use case, you may want to verify the identity of all users, or only some. For example, you might want to verify the identity of any user initiating a funds transfer, or you might only verify users who you have identified as being higher risk, based on data such as email address, location, financial institution, or activity patterns.

Plaid Identity can be combined with [Plaid Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) in a single workflow to provide full identity verification and fraud reduction. [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) is used for KYC, to verify that the user of your app is the person they claim to be, while Identity is used to confirm that the ownership information on their linked bank or credit card account matches this verified identity.

#### Integration overview 

1.  Create a Link token by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
    *   If you are using Identity as a best-effort adjunct to other products, like Auth, put `identity` in the `required_if_supported_products` array.
    *   If you want to require Identity and fail sessions where Identity data is not available, put `identity` in the `products` array.
2.  Initialize Link with the Link token from the previous step. For more details, see [Link](https://plaid.com/docs/link/index.html.md) .
3.  Once the user has successfully completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .
4.  Once you have the `access_token`, call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) to get data, or [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) to match data. For more information on [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , including optional streamlined integration modes, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) .

#### Getting Identity data 

The [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) endpoint provides you with several pieces of information. The name is guaranteed to be available; the email address, phone number, and address are usually available, but may be `null` otherwise.

##### Sample Identity data 

Identity data returned by [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) includes owners' names, addresses, email addresses, and phone numbers as reported by the financial institution. In the case of an Item containing accounts with multiple owners, all owners' information will be provided. For business accounts, the account owner’s name can be that of a business.

```json
"owners": [
  {
    "addresses": [
      {
        "data": {
          "city": "Malakoff",
          "country": "US",
          "postal_code": "14236",
          "region": "NY",
          "street": "2992 Cameron Road"
        },
        "primary": true
      }
    ],
    "emails": [
      {
        "data": "accountholder0@example.com",
        "primary": true,
        "type": "primary"
      },
      {
        "data": "accountholdersecondary0@example.com",
        "primary": false,
        "type": "secondary"
      },
    ],
    "names": [
      "Alberta Bobbeth Charleson"
    ],
    "phone_numbers": [
      {
        "data": "1112223333",
        "primary": true,
        "type": "home"
      }
    ]
  }
]
```

##### Typical identity fill rates by field 

| Field | Typical fill rate |
| --- | --- |
| Name | 100% |
| Email address | 98% |
| Address | 93% |
| Phone number | 90% |

#### Identity Match 

Using [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , Identity data fields such as names, addresses, email addresses, and phone numbers can be matched against the owners’ identity information on connected accounts. Multiple fields are matched in a single request, and a separate score is returned for each field to indicate how closely it matched. Customers using Identity Match can experience onboarding conversion improvements of 20% or more, without increasing fraud rates, when using Identity Match versus using their own matching algorithms.

If you are using [Auth](https://plaid.com/docs/auth/index.html.md) , you can optionally integrate Identity Match via the Dashboard with no additional code. For details, see [Integrating Identity Match via the Account Verification Dashboard](https://plaid.com/docs/identity/index.html.md#integrating-identity-match-via-the-account-verification-dashboard) .

If you are already using [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , you can further enhance your verification process by enabling Financial Account Matching in your Identity Verification template. This feature allows you to match the data collected during KYC without having to specify the `user` field in your [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) request. To ensure accurate matching, it's important to maintain consistency in the `client_user_id` used for end users across all products.

##### Sample Identity Match data 

Data returned by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) includes scores from matching a user's name, address, phone number, and email with the account owner's data that was present on the connected account. A score ranging from 0 to 100 is provided for each identity field. The score for a given field will be missing if the identity information for that field was not provided in the request or unavailable at the connected account. In the case of an Item containing accounts with multiple owners, the highest matched scores are returned.

You should typically not set the match score requirement for a field to 100. For example, if a phone number match score of 100 is required, the presence or absence of a country code, parentheses, or other formatting differences may cause a phone number mismatch. 70 is the default recommended match score threshold for all fields.

###### Example of how to interpret name match score 

| Range | Meaning | Example |
| --- | --- | --- |
| 100 | Exact match | Andrew Smith, Andrew Smith |
| 85-99 | Strong match, likely spelling error, nickname, or a missing middle name, prefix or suffix | Andrew Smith, Andrew Simth |
| 70-84 | Possible match, likely alias or nickname and spelling error | Andrew Smith, Andy Simth |
| 50-69 | Unlikely match, likely relative | Andrew Smith, Betty Smith |
| 0-49 | Unlikely match | Andrew Smith, Ray Charles |

###### Example of how to interpret phone number score 

| Range | Meaning | Example |
| --- | --- | --- |
| 100 | Exact match | +1-555-867-5309, +1-555-867-5309 |
| 90-99 | Same phone number, likely different formatting | +1-555-867-5309, 1 (555)-867-5309 |
| 70-89 | Same phone number, likely different formatting and/or missing country code | +1-555-867-5309, 5558675309 |
| 0-69 | Unlikely match | +1-555-867-5309, 555-867-5302 |

```json
{
  "accounts": [
    {
      ..
      "legal_name": {
        "score": 90,
        "is_nickname_match": true,
        "is_first_name_or_last_name_match": true
      },
      "phone_number": {
        "score": 100
      },
      "email_address": {
        "score": 100
      },
      "address": {
        "score": 100,
        "is_postal_code_match": true
      },
      ..
    },
  ]
}
```

##### Using Identity Match with micro-deposit or database Items 

Items verified via [Same Day micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) , [Instant micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) , or [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) are not typically compatible with any other Plaid products besides Auth and Transfer. An exception is Identity Match, which can be used with these Items if they were previously seen on the Plaid network (approximately 30% of these Items).

Note that this applies to the Identity Match endpoint only; Items created using these flows are not compatible with [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) .

To use Identity Match with micro-deposit or database Items, you have two options:

*   For a low-code option that allows you to run the Identity Match check within the Link flow, use the [Account Verification Dashboard](https://plaid.com/docs/identity/index.html.md#integrating-identity-match-via-the-account-verification-dashboard) .
*   To run the Identity Match check outside the Link flow, continue with the [integration instructions in this section](https://plaid.com/docs/identity/index.html.md#integration-instructions) .

###### Integration instructions 

1.  To enable the Item for Identity Match, `identity` must be included in the `optional_products`, `required_if_supported_products`, or `additional_consented_products` array during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call at Item creation. (For this flow, `identity` should not be included in the `products` array, since including any other product than `auth` in the `products` array can prevent micro-deposit or database verification flows from activating.)
    *   If this was not done during Item creation, you can Identity consent to an existing Item by sending it through [update mode](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) .
2.  Call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) .

If the Item is supported by Identity Match, you will receive results. If the Item was not previously seen on the Plaid network and therefore cannot be used with Identity Match, you will receive a `PRODUCTS_NOT_SUPPORTED` error and will not be billed for the API call.

#### Integrating Identity Match via the Account Verification Dashboard 

If you are using [Auth](https://plaid.com/docs/auth/index.html.md) , you can integrate Identity Match via the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) . This is a lower-code option that allows you to rely on Plaid Link for checking match scores and handling failed sessions.

When enabling Identity in this way, the Identity check will be incorporated into the Link flow.

This configuration option can only be used if Auth and Identity are the only required Plaid products you are using in the session. If you need access to other products, use the [standard integration flow](https://plaid.com/docs/identity/index.html.md#integration-overview) .

1.  In the [Dashboard](https://dashboard.plaid.com/account-verification) , select your Link customization and enable the "Configure via Dashboard" toggle.
2.  Select the settings for Auth you would like to use, then click "Next".
3.  Select the rules to use for Identity Match. Typically, the match threshold for each field should be set to a score of 70 or higher.
4.  When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) :
    *   Ensure that `identity` is in the `products` array (or `required_if_supported_products` array, if you want to allow customers to link accounts if their bank does not support Identity).
    *   Set the `link_customization_name` to the customization you selected in Step 1 (this is optional if you are using the `default` customization).
    *   Provide the identity data you have about the user, such as their `legal_name`, `phone_number`, `address`, and `email_address`.
5.  Launch Link using the Link token. When the user goes through the Link flow, the identity data you supplied in the previous step will be compared to the data retrieved from their linked financial account. If the result based on your configuration is a pass, they will see a success screen. If it is a failure, they will see an error.
6.  Watch for the `IDENTITY_MATCH_PASSED` or `IDENTITY_MATCH_FAILED` event from Link to detect the result of Identity Match in the Link flow. You can also view the status of a completed session in the [Dashboard](https://dashboard.plaid.com/account-verification) .

If the Identity Match check fails, you will not receive a `HANDOFF` event or `onSuccess` callback, but if you want to proceed with creating an Item anyway, you can obtain the `public_token` by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) .

If Identity is enabled via the Account Verification Dashboard, you will be billed for Identity Match as long as Plaid could obtain any Identity data from the Item, even if you did not exchange the `public_token`. If Plaid was unable to obtain any Identity data for the Item, you will not be billed.

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

#### Testing Identity 

Identity can be tested in Sandbox against test data. Plaid provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) with test data for testing Identity in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) .

[/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) can be tested in Sandbox using custom user accounts as described above. Note that it is not recommended to send real user data or PII in the Sandbox environment for use with [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , as Sandbox is meant for testing purposes.

For details on testing Identity Match with Same Day Micro-deposits, see [Testing Same-Day Microdeposits](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) .

When testing Identity Match using the default `user_good` custom Sandbox user, you can expect the following identity data to be used for matching against:

```undefined
Alberta Bobbeth Charleson
2992 Cameron Rd.
Malakoff, NY 14236
Phone: +1-111-222-3333
Email: accountholder0@example.com
```

#### Identity Document Upload 

The [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) add-on can be used to verify account ownership based on a bank statement uploaded by an end user. This feature is intended primarily for use with Items created via loginless Auth flows, such as Same-Day Micro-deposits, Instant Micro-deposits, or Database Insights. For more details, see [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) .

#### Sample app tutorial and code 

For a real-life example of an app that incorporates Identity, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Identity data in order to verify identity prior to a funds transfer. The Identity code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L116) .

For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) .

#### Identity pricing 

Identity is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) , meaning you will be billed once for each Item with Identity added to it. Identity Match is billed on [a per-request flat-fee basis](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Identity availability by country 

Identity and Identity Match are available in all supported countries (US, Canada, and Europe, including the UK). In Canada, Identity Match cannot be requested via the Production access form and is available via a Growth or Custom plan only. To request access to Identity Match in Canada, contact your account manager or [Sales](https://plaid.com/contact/) .

#### Next steps 

To get started building with Identity, see [Add Identity to your App](https://plaid.com/docs/identity/add-to-app/index.html.md) .

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Income - Add Income to your app | Plaid Docs

Add Income to your app 
=======================

#### Use Income to fetch income information about your users 

This guide will walk you through how to use [Income](https://plaid.com/docs/api/products/income/index.html.md) to retrieve information about your users' current sources of income.

This is a basic quickstart guide that does not cover all features of the Income product. For more complete information about Income endpoints and capabilities, see the individual product pages for [Bank Income](https://plaid.com/docs/income/bank-income/index.html.md) , [Document Income](https://plaid.com/docs/income/document-income/index.html.md) , and [Payroll Income](https://plaid.com/docs/income/payroll-income/index.html.md) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard if you wish to retrieve real data in Production. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) , and must be completed before connecting to certain institutions.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create a User Token 

Unlike many other Plaid products, where you start by creating `Items` to represent user connections with individual banks, with Income you first start by creating a `user_token` that represents an individual user. As you add various sources of income, those will all be associated with this single `user_token`, which allows you to receive consolidated income from different sources by requesting an income report for that `user_token`.

To create a `user_token`, make a call to the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. This endpoint requires a unique `client_user_id` value to represent the current user. Typically, this value is the same identifier you're using in your own application to represent the currently signed-in user. This call will return a randomly-generated string for the `user_token` as well as a separate user ID that Plaid includes in webhooks to represent this user.

You can only create one `user_token` per `client_user_id`. If you try to create a `user_token` with a `client_user_id` that you have previously sent to Plaid, you will receive an error.

Depending on your application, you might wish to create this `user_token` as soon as your user creates an account, or right before they begin the process of confirming their income data with you.

```javascript
const { IdentityGetRequest } = require('plaid');


// Pull Identity data for an Item
const request: IdentityGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.identityGet(request);
  const identities = response.data.accounts.flatMap(
    (account) => account.owners,
  );
} catch (error) {
  // handle error
}


// The userId here represents the user's internal user ID with your
// application
const createUserToken = async (userId) => {
  const response = await plaidClient.userCreate({
    client_user_id: userId,
  });
  const newUserToken = response.data.user_token;
  const userIdForWebhooks = response.data.user_id;
  await updateUserRecordWithIncomeInfo(userId, newUserToken, userIdForWebhooks);
};
```

#### Decide what income verification method(s) you want to support 

Income supports three different ways that a user can verify their sources of income.

*   _Payroll Income_ allows Plaid to retrieve information such as recent pay stubs and W-2 forms directly from the user's payroll provider. This tends to provide the most comprehensive data, but is dependent upon the user being able to sign in with their payroll provider.
*   _Document Income_ allows the user to upload images of income-related documents (such as pay stubs and W-2 forms), which Plaid can scan and interpret for you.
*   _Bank Income_ allows the user to connect with their bank to identify deposits that represent sources of income.

Depending on which methods you want to support (and it's perfectly acceptable to support all three), you will need to implement slightly different processes. While you can collect Payroll and Document Income in the same Link flow, you cannot collect Payroll or Document Income in the same Link flow as Bank Income.

### Fetching Payroll or Document Income data 

The process for implementing Payroll and Document Income is very similar, so we'll cover these two scenarios next.

#### Create a Link token for Payroll or Document Income 

Plaid Link is a drop-in module that provides a secure, elegant UI flow to guide your users through the process of connecting Plaid with their financial institutions. With Income, Link can help your user search for and connect to their payroll provider as well as assist them in uploading documents.

Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the appropriate section in the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, single-use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, initialize Link with the `link_token` that you just created.

When calling the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint, you'll include an object telling Plaid about your application as well as how to customize the Link experience. When creating a `link_token` for Payroll or Document Income, there are a few extra values you'll need to supply in this object:

*   You will need to pass in the `user_token` that you created earlier.
*   You can only list `"income_verification"` in the list of products
*   You will need to create an object with `income_source_types` set to `["payroll"]` and pass that as the value for `income_verification`

Note that in the code sample below, in addition to passing in a `user_token`, we are also passing in the signed in user's ID as the `user.client_user_id` value. These are fundamentally different user IDs used for different purposes. The `user.client_user_id` value is primarily used for logging purposes and allows you to search for activity in the Plaid Dashboard based on the user ID. While its value is most likely the same user ID that you passed in when creating the `user_token` above, they are otherwise unrelated.

```javascript
// Using Express


app.post('/api/create_link_token_for_payroll_income', async function (
  request,
  response,
) {
  // Get the client_user_id by searching for the current user.
  const clientUserId = await GetSignedInUserId();
  // Get the Plaid user token that we stored in an earlier step
  const userToken = await GetPlaidTokenForUser();
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['income_verification'],
    user_token: userToken,
    income_verification: {
      income_source_types: ['payroll'],
    },
    language: 'en',
    webhook: 'https://webhook.example.com',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

By default, a `link_token` created this way will allow the user to collect income information using both the Payroll and Document methods. However, in some cases you might want to permit the user to only use one of these methods. To do that, you can specify the `flow_types`, as in the example below.

```javascript
income_verification: {
  income_source_types: ["payroll"],
  payroll_income: { flow_types: ["payroll_digital_income"] },
},
```

##### Install the Link library 

You need to install the Link JavaScript library from Plaid in order to use Link in your web application.

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

To run Link, you'll first need to retrieve the `link_token` from the server using the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) described above. Then, call `Plaid.create()`, passing along that token alongside other callbacks you might want to define. This will return a handler that has an `open` method. Call that method to open up the Link UI and start the connection process.

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/api/create_link_token_for_payroll_income')).link_token,
  onSuccess: (public_token, metadata) => {
    // Typically, you'd exchange the public_token for an access token.
    // While you can still do that here, it's not strictly necessary.
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

If you've had experience with other Plaid products, you're probably used to taking the `public_token` received from Link and exchanging it on your server for a persistent `access_token`. However, because Payroll and Document Income are fetched once (and don't require persistent connections with your user's bank), and all of your reports are associated with the user's `user_token`, there's no need to retrieve or store an `access_token` in this case.

#### Listen for webhooks 

After a user has finished using Link, it may take some time before Plaid has the user's income information available for you to download. In the case of Payroll Income, this typically takes a few seconds. For Document Income, this may take several minutes. Listen for the `INCOME: INCOME_VERIFICATION` webhook to know when this user's data is ready.

```javascript
app.post('/server/receive_webhook', async (req, res, next) => {
  const product = req.body.webhook_type;
  const code = req.body.webhook_code;
  if (product === 'INCOME' && code === 'INCOME_VERIFICATION') {
    const plaidUserId = req.body.user_id;
    const verificationStatus = req.body.verification_status;
    if (verificationStatus === 'VERIFICATION_STATUS_PROCESSING_COMPLETE') {
      await retrieveIncomeDataForUser(plaidUserId);
    } else {
      // Handle other cases
    }
  }
  // Handle other types of webhooks
});
```

The `user_id` value included in this webhook is the same `user_id` that was returned by Plaid when you first created a `user_token` for this user.

#### Fetch income data 

Now that Plaid has confirmed it has finished processing this user's data, you can fetch the data by making a call to the [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) endpoint. Pass in the `user_token`, and Plaid will return all Payroll and Document Income sources associated with that token.

```javascript
try {
  const response = await plaidClient.creditPayrollIncomeGet({
    user_token: userToken,
  });
  const incomeData = response.data;
  // Do something interesting with the income data here.
} catch (error) {
  // Handle error
}
```

This call will typically return an array of `items`, each of which represents a connection with a payroll provider. These `items`, in turn, contain one or more `payroll_income` objects that contain detailed payroll information for the user. This can include individual pay stubs (with a full breakdown of gross pay, deductions, net pay, and more), as well as W-2 forms and all of their information. See the [sample response object](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) in the documentation for a full example of what this response might look like.

You can distinguish between income that was retrieved through Payroll Income and income that was retrieved through Document Income by looking for an `account_id` value on the `payroll_income` object. If the data was retrieved through scanning user documents, this value will be null.

### Fetching Bank Income data 

As an alternative to downloading income data from the user's payroll provider or W-2 forms, Plaid can also find income data in the user's bank account. Plaid will look for deposits that might be sources of income and ask the user to identify which deposits represent income that they wish to share with your application.

#### Create a Link token for Bank Income 

Creating a `link_token` for Bank Income is similar to the process for creating a `link_token` for Payroll or Document Income. The main differences are:

*   While you still must include `"income_verification"` as a product, you are allowed to combine this product with other products that you might want to use with this financial institution.
*   Your `income_source_types` must be set to `["bank"]`.
*   Your `income_verification` object must also include a `bank_income` object, where you have set the value of `days_requested`. This is the number of days back that Plaid will search for regularly occurring deposits.

The value of `days_requested` should a large enough number that you find all relevant deposits, but not so large that the user gets tired waiting for Plaid to retrieve all the relevant data. We recommend 120 days as good balance between the two.

```javascript
app.post('/api/create_link_token_for_bank_income', async function (
  request,
  response,
) {
  // Get the client_user_id by searching for the current user.
  const clientUserId = await GetSignedInUserId();
  // Get the Plaid user token that we stored in an earlier step
  const userToken = await GetPlaidTokenForUser();
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['income_verification', 'transactions', 'assets'],
    user_token: userToken,
    income_verification: {
      income_source_types: ['bank'],
d       bank_income: { days_requested: 120 },
    },
    language: 'en',
    webhook: 'https://webhook.example.com',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install the Link library 

As described earlier, you need to install the Link JavaScript library from Plaid to use Link in your web application.

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

Retrieve the `link_token` from the server, then call `Plaid.create()`, passing along the `link_token` alongside other callbacks you might want to define. This will return a handler that has an `open` method, which you can call to start the Link process. This is similar to the process described above, but with Bank Income you will probably want to keep the `public_token` and exchange it for an `access_token`, as described in the next step.

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/api/create_link_token_for_bank_income')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

##### Retrieve metadata about the Link session 

Call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) in your server after receiving `onSuccess`, passing in the `link_token`. If you enabled [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you should instead wait for the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook rather than the `onSuccess` frontend callback, to ensure that the Link flow is complete, and all Items have been linked. For more details, see the [Multi-Item Link docs](https://plaid.com/docs/link/multi-item-link/index.html.md) .

Previously, customers were instructed to call [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) to obtain the public token. While this flow is still supported, all customers are encouraged to use the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint to obtain the public token instead, for improved consistency with other Plaid products and flows.

```javascript
try {
  const response = await plaidClient.linkTokenGet({
    link_token: LinkToken,
  });
  const sessionData = response.data;
} catch (error) {
  // Handle this error
}
```

If you are using other Plaid products such as Auth or Balance alongside Bank Income, make sure to capture the `public_token` (or tokens) from the `results.item_add_result` field and exchange it for an `access_token`.

#### Get a persistent access token (for other products) 

For the purpose of retrieving income data, you don't necessarily need an `access_token`. Plaid will retrieve the income data for you, and then that data will be associated with the `user_token` that you created when first configuring Link.

However, if you are using any other product with this financial institution (such as Transactions, Balance, or Assets), you will need to exchange your `public_token` for an `access_token` and `item_id`. The `access_token` lets you make authenticated calls to these other products in the Plaid API.

Exchanging a `public_token` for an `access_token` is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from the server-side handler. Store the `access_token` and `item_id` that get returned in a secure server-side location. Never store this information on the client.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Fetch income data 

You can fetch income data by calling the [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) endpoint using the Plaid client library, passing in the `user_token` you created earlier. Note that, similar to Document or Payroll Income, this data is static -- it is a snapshot of the user's income data that was retrieved by Plaid when the user ran Link. It does not update or change over time.

By default, Plaid will only return the most recent report in its response. However, you might want to retrieve more than one report if your user has intentionally run Link multiple times. You can do this by passing an `options` object with a `count` value set to an integer.

```javascript
try {
  const response = await plaidClient.creditBankIncomeGet({
    user_token: userRecord[FIELD_USER_TOKEN],
    options: {
      count: 3,
    },
  });
  const bankIncomeData = response.data;
} catch (error) {
  // Handle this error
}
```

This call typically returns a `bank_income` array, which consists of a number of different objects that represent the report generated when the user ran Link. These individual reports contain an `items` array, which in turn contains one or more objects that represent the financial institutions associated with this report. These objects contain a `bank_income_accounts` array of objects, which gives you information about the individual accounts, as well as a `bank_income_sources` array of objects, which in turn contains the total amount of income reported, along with historical transactions about that income.

Each report also contains a `bank_income_summary` object, that summarizes the total bank income identified across all items in this report.

#### Example code 

For an example of an app that incorporates Document, Payroll and Bank Income, see the React and Node-based [Income Sample app](https://github.com/plaid/income-sample) . The Income Sample app is an application that uses Income and Liability data to help determine whether the user can qualify for financing on a pre-owned hoverboard. It supports the use of all three types of income data.

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Income - Bank Income | Plaid Docs

Bank Income 
============

#### Learn about Bank Income features and implementation 

Get started with Bank Income

[API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample) [Income Verification Demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100)

#### Overview 

Bank Income allows you to instantly retrieve net income information from a user-connected bank account, supporting both irregular or gig income and W-2 income. Data available includes a breakdown of income streams to the account, as well as recent and historical income.

[Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE)

For all new integrations supporting end users based in the US, Plaid recommends the use of [Consumer Report Income Insights](https://plaid.com/docs/check/index.html.md) instead of Bank Income. Income Insights provides FCRA compliant insights and bundles income calculations (historical average income, forecasted income, predicted next payment date) in a single report. For more information, see [Plaid Check Consumer Report](https://plaid.com/docs/check/index.html.md) .

#### No-code Income integration with the Credit Dashboard 

Bank Income can be used as part of a no-code integration flow. This integration mode is available only when using Income alongside Assets. For more details, see the [Assets no-code integration guide](https://plaid.com/docs/assets/index.html.md#no-code-integration-with-the-credit-dashboard) .

#### Integration process 

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token` that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type.
2.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following:
    *   For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   For `products`, use `["income_verification"]`. You can also specify additional products. For more details, see [Using Bank Income with other products](https://plaid.com/docs/income/bank-income/index.html.md#using-bank-income-with-other-products) .
    *   For `income_verification.income_source_types`, use `bank`.
    *   Set `income_verification.bank_income.days_requested` to the desired number of days.
    *   Provide a `webhook` URI with the endpoint where you will receive Plaid webhooks.
3.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
4.  Open Link in your web or mobile client and listen to the `onSuccess` and `onExit` callbacks, which will fire once the user has finished or exited the Link session.
5.  If you are using other Plaid products such as Auth or Balance alongside Bank Income, call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) and make sure to capture each `public_token` from the `results.item_add_results` array. Exchange each `public_token` for an `access_token` using [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . For more details on token exchange, see the [Token exchange flow](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) .
6.  To retrieve data, call [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) with the `user_token`.

#### Multi-Item sessions 

Many users get income deposited into multiple institutions. To help capture a user’s full income profile, you can allow your users to link multiple accounts within the same link session on web integrations.

(An image of "Select bank, enter credentials, choose income transactions, and review income in Plaid's bank income flow.")

Bank Income Multi Item Link flow

To enable this flow, see [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . The previous Income-specific flow, which used the `income_verification.bank_income.enable_multiple_items` setting in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and obtained public tokens from the [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) endpoint, has been deprecated and replaced with a generic Multi-Item Link flow that supports all Plaid and Plaid Check products.

#### Using Bank Income with other products 

Bank Income Items are fully compatible with other Plaid Item-based products, including Auth, Transactions, Balance, and Assets.

When initializing Link, if you plan to use Bank Income and Assets in the same session, it is recommended to put both `income_verification` and `assets` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `products` array. If you plan to use Bank Income with Transactions, you should not put `transactions` in the `products` array, as this may increase latency. For more details, see [Choosing how to initialize Link](https://plaid.com/docs/link/initializing-products/index.html.md) .

To capture an `access_token` for use with other products, call [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) after receiving the `onExit` or `onSuccess` callback from Link. This endpoint will return all `public_token`s for every Item linked to a given `user_token`. For details on the API schema, see the [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) documentation. You can then exchange these `public_tokens` for `access_tokens` using [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .

#### Verifying Bank Income for existing Items 

If your user has already connected their depository bank account to your application for a different product, you can add Bank Income to the existing Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

To do so, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request described above, populate the `access_token` field with the access token for the Item. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Income Verification step. Otherwise, they will be prompted to complete the full Plaid Bank Income Link flow.

#### Bank Income Refresh 

Bank Income Refresh is available as an optional add-on to Bank Income. With Bank Income Refresh, you will be able to get updated income data for a user. Existing income sources will be updated with new transactions, and new income sources will be added if detected.

To implement Bank Income Refresh:

1.  On the [webhooks page in the Dashboard](https://dashboard.plaid.com/developers/webhooks) , enable Bank Income Refresh webhooks and (optionally) Bank Income Refresh Update webhooks.
    
2.  Call [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) with the `user_token` for which you want an updated report.
    
3.  A [BANK\_INCOME\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/income/index.html.md#bank_income_refresh_complete) webhook will notify you when the process has finished. If the value of the `result` field in the webhook body is `SUCCESS`, the report was updated. If it was `FAILURE`, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) and then try calling [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) again.
    
4.  If the report was updated, when you next call [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) or [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) , the refreshed version of the report will be returned. To see old versions of the report, call [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) with the `options.count` parameter set to a number greater than 1.
    

#### Institution coverage 

To determine whether an institution supports Bank Income, you can use the Dashboard status page (look for "Bank Income") or the [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint (look for or filter by the `income_verification` product). The `income` product returned by these surfaces represents a legacy product and does not indicate coverage for Bank Income.

#### Testing Bank Income 

In Sandbox, you can use the user `user_bank_income` with the password `{}`. The basic [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#sandbox-simple-test-credentials) (`user_good`/`pass_good`) will not return data when used to test Bank Income.

Plaid also has additional test users for scenarios such as joint accounts, bonus income, and different levels of creditworthiness: for details, see [Credit and Income testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) .

When using special Sandbox test credentials (such as `user_bank_income` / `{}`), use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) flow or a non-OAuth test institution, such as First Platypus Bank (`ins_109508`). Special test credentials may be ignored when using the Sandbox Link OAuth flow.

If you’d like to test Bank Income with custom data, Plaid provides several [test JSON configuration objects](https://github.com/plaid/sandbox-custom-users/tree/main/income) . To load this data into Sandbox, copy and paste the JSON into a new custom user via the [Sandbox Users pane](https://dashboard.plaid.com/developers/sandbox) in the Dashboard.

[/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) can optionally be tested in Sandbox without using Link. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and pass the returned `user_token` to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) . [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) must be called with the following request body:

```bash
{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "institution_id": "ins_20", //any valid institution id is fine
  "initial_products": ["income_verification"],
  "user_token": "user-token-goes-here", //use the user_token from the `/user/create` call made earlier
  "options": {
    "override_username": "user_bank_income", //or other test user from Credit and Income testing credentials
    "override_password": "{}",
    "income_verification": {
      "income_source_types": ["bank"],
      "bank_income": {
        "days_requested": 120 //any number of days under 730 is valid
      }
    },
  }
}
```

After calling [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) , call [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) using the same `user_token`. The output of [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) will not be used, but calling it initializes the user token for testing.

#### Bank Income pricing 

Bank Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . Bank Income Refresh is billed on a [per-request fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Income - Document Income | Plaid Docs

Document Income 
================

#### Learn about Document Income features and implementation 

Get started with Document Income

[API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample)

#### Overview 

Document Income allows you to retrieve gross and/or net income information via user-uploaded documents such as a pay stub, bank statement, W-2, or 1099 form.

[Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE)

#### Integration process 

1.  (Optional) Update your [Link customization](https://dashboard.plaid.com/link/manualVerificationOfIncomeUpload) in the Dashboard to configure which types of documents a user can upload to verify their income. By default, if you do not change this setting, only pay stubs are accepted.
2.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token` that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type.
3.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following:
    *   For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   For `products`, use `["income_verification"]`. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income.
    *   For `income_verification.income_source_types`, use `payroll`.
    *   (Optional) If you are only using Document Income and do not want customers to use Payroll Income, for `income_verification.payroll_income.flow_types`, use `["payroll_document_income"]`.
    *   Provide a `webhook` URI with the endpoint where you will receive Plaid webhooks.
    *   If using Fraud Risk, set `income_verification.payroll_income.parsing_config` to either `['risk_signals']` or `['risk_signals', 'ocr']`. For more details, see [Fraud Risk detection](https://plaid.com/docs/income/document-income/index.html.md#fraud-risk-detection) .
4.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see [Link](https://plaid.com/docs/link/index.html.md) .
5.  Open Link in your web or mobile client and listen to the `onSuccess` and `onExit` callbacks, which will fire once the user has finished or exited the Link session.
6.  If using Fraud Risk, wait for the [INCOME: INCOME\_VERIFICATION\_RISK\_SIGNALS](https://plaid.com/docs/api/products/income/index.html.md#income_verification_risk_signals) webhook, then call [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) .
    *   If the document requires manual review, call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) to get a URI where the user's original documents can be downloaded.
7.  If using Document Parsing, wait for the [INCOME: INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook, then call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and/or [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) to obtain parsed income details. You can use [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) to see what document types were uploaded, which will determine which of the two endpoints to call. For details, see [Document Parsing](https://plaid.com/docs/income/document-income/index.html.md#document-parsing) .

#### Fraud risk detection 

To detect potential document fraud or document tampering during the Document Income flow, you can use the optional Fraud Risk feature. Fraud Risk's AI-powered analysis scans for over two dozen different fraud signals within categories such as: visual evidence of tampering, suspicious metadata, inconsistent contents, and similarity to known fraudulent documents. If your account is not enabled for this feature, contact sales or your Plaid Account Manager to request access.

To enable Fraud Risk:

1.  When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , set the `income_verification.payroll_income.parsing_config` array to include `'risk_signals'`. By default, this will disable [Document Parsing](https://plaid.com/docs/income/document-income/index.html.md#document-parsing) ; to keep it enabled, include `'ocr'` in the array as well.
2.  When the risk analysis has been completed, you will receive an [INCOME\_VERIFICATION\_RISK\_SIGNALS](https://plaid.com/docs/api/products/income/index.html.md#income_verification_risk_signals) webhook. This webhook may take up to 45 minutes to fire.
3.  Once the webhook has been received, call the [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) endpoint.

[/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) will return a risk score for each document, as well as a detailed set of reasons for any potential risk.

You can automatically reject documents with a high risk score, automatically accept documents with a low risk score, and manually review documents in between. We suggest starting with a threshold of 80 for auto-rejection and 20 for auto-acceptance. As you gather more data points on typical risk scores for your use case, you can tune these parameters to reduce the number of documents undergoing manual review.

To obtain a copy of the original document for manual review, call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and use the `document_metadata.download_url`.

To enable Fraud Risk on a verification where the Link flow has already been completed, use the [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) endpoint.

#### Document Parsing 

Document Parsing is an optional feature that allows you to obtain a JSON representation of an uploaded document. If your account is not enabled for this feature, contact sales or your Plaid Account Manager to request access.

To enable Document Parsing:

1.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as normal, then launch Link and have the user go through the Link flow. You do not need to specify a `parsing_config` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , as Document Parsing will be enabled by default if this field is omitted. However, if this field is supplied (for example, to enable Fraud Risk), it must include `ocr` to enable Document Parsing.
    
2.  To see which file types a user uploaded, use [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) . The `document_income_results` field will show how many of each filetype were uploaded.
    
3.  Wait for document parsing to complete, which will be indicated by the [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook. This webhook may take up to 45 minutes to fire.
    
4.  Once the webhook has been received, to obtain parsed JSON data from a pay stub, W-2, or 1099, use [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . To obtain parsed JSON data from a bank statement, use [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) .
    

To enable Document Parsing on a verification where the Link flow has already been completed, use the [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) endpoint.

#### Downloading original documents 

To download the original user-uploaded documents, use the `document_metadata.download_url` returned by [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) .

#### Customizing document uploads 

To configure which documents your users can upload, create a [Link customization in the Dashboard](https://dashboard.plaid.com/link) . You must update this setting in order to accept documents other than pay stubs.

##### Supported document types 

*   Pay stubs
*   Bank statements
*   W-2
*   1099-K
*   1099-MISC

##### Supported file types 

*   PDF
*   PNG
*   JPEG
*   GIF
*   BMP
*   TIFF

For more details, see [Document upload settings](https://plaid.com/docs/link/customization/index.html.md#document-income-only-document-upload-settings) .

#### Testing Document Income 

In the Sandbox environment, when testing Document Income, by default, the contents of the actual document will not be processed and Sandbox will instead use pre-populated test data. You can customize the response you get by uploading JSON files with a custom configuration schema in the Link flow. Each JSON file will represent one document in the response and can include customizations for:

*   Either a paystub or a W-2
*   Risk signals
*   OCR parsing status
*   Risk signals status

The customization schema for each document and risk signals is very similar to the objects in the responses from [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) . Example JSON files that you can adapt can be found in the [Custom Sandbox User GitHub repo](https://github.com/plaid/sandbox-custom-users/tree/main/income/document_income) .

#### Document Income pricing 

Document Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . The fee depends on the number and type of documents processed and which processing options are enabled (i.e. fraud risk, document parsing, or both).

To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Income - Introduction to Income | Plaid Docs

Introduction to Income  
========================

#### Optimize your income verification process with document, payroll, and bank-based Income verification 

Get started with Income

[API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample) [Demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100)

#### Overview 

Plaid Income (currently US, CA, and UK only) helps you verify anyone's income and employment in seconds, facilitating an improved decisioning and underwriting process. Depending on the Income product you choose, you can request information such as pay stub data, income streams, and historical income.

You can enable multiple different methods of income verification, then use the appropriate one for your situation. For example, you might enable Bank Income and also provide Document Income as a fallback for customers who prefer not to link their bank account or don't bank with a Plaid-supported institution.

You can verify a user's income via three products:

[Document Income:](https://plaid.com/docs/income/document-income/index.html.md) Retrieve gross and/or net income information via user-uploaded documents such as a pay stub, bank statement, W-2, or 1099 form.

[Payroll Income (US only):](https://plaid.com/docs/income/payroll-income/index.html.md) Instantly retrieve employment and gross income information, including the information available on a pay stub, from a user-connected payroll account. Supports approximately 80% of the US workforce, including gig income workers.

[Bank Income:](https://plaid.com/docs/income/bank-income/index.html.md) Instantly retrieve net income information from a user-connected bank account. Data available includes a breakdown of income streams to the account, as well as recent and historical income.

Most new customers should consider [Consumer Report Income Insights](https://plaid.com/docs/check/index.html.md) instead of Bank Income. Income Insights is an FCRA-compliant product providing details on over a dozen categorized income streams along with ready-made, model-driven attributes like historical gross and net income to streamline debt-to-income calculations and income verification. It also provides details like forecasted income, employer name, income frequency, and predicted next payment date.

Income is recommended for use cases not supported by Income Insights, such as underwriting outside the US, or Payroll or Document Income based flows.

For a fuller view of a borrower's financial situation, Income can be used with [Assets](https://plaid.com/docs/assets/index.html.md) , which provides user-permissioned income streams derived from deposit activity.

If you need exact copies of a user's statements, see [Statements](https://plaid.com/docs/statements/index.html.md) .

For a fuller view of a borrower's financial situation, Income can also be used with [Assets](https://plaid.com/docs/assets/index.html.md) , which provides user-permissioned asset verification.

Income is a product of Plaid Inc., which is not a consumer reporting agency. To learn more about products offered by Plaid Consumer Reporting Agency, Inc., (Plaid CRA) see [Plaid Check](https://plaid.com/docs/check/index.html.md) . Income can't be used in the same Link flow as Plaid CRA products.

[Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE)

#### Next steps 

To learn more about integrating Income, see the docs for the Income product you would like to use: [Document Income](https://plaid.com/docs/income/document-income/index.html.md) , [Payroll Income](https://plaid.com/docs/income/payroll-income/index.html.md) , or [Bank Income](https://plaid.com/docs/income/bank-income/index.html.md) .

---


# Income - Payroll Income | Plaid Docs

Payroll Income 
===============

#### Learn about Payroll Income features and implementation 

Get started with Payroll Income

[API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample)

#### Overview 

Payroll Income (US only) allows you to instantly verify employment details and gross income information, including the information available on a pay stub, from a user-connected payroll account. Payroll Income supports approximately 80% of the US workforce, including gig income workers.

[Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE)

#### Integration process 

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token` that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type.
2.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following:
    *   For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   For `products`, use `["income_verification"]`. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income.
    *   For `income_verification.income_source_types`, use `payroll`.
    *   (Optional) If you are only using Payroll Income and do not want customers to use Document Income, for `income_verification.payroll_income.flow_types`, use `["payroll_digital_income"]`.
    *   Provide a `webhook` URI with the endpoint where you will receive Plaid webhooks.
3.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see [Link](https://plaid.com/docs/link/index.html.md) .
4.  Open Link in your web or mobile client and listen to the `onSuccess` and `onExit` callbacks, which will fire once the user has finished or exited the Link session.
5.  Listen for the [INCOME: INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook, which will fire within a few seconds, indicating that the Income data is ready.
6.  Call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) for income data, and/or [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) for employment details.

#### Payroll Income Refresh 

To request access to Payroll Income Refresh, contact your account manager.

On-demand Payroll Income Refresh allows you to request updated information from a previously connected payroll account.

To trigger a refresh, call [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) and specify the `user_token` to refresh.

If the refresh is successful, you will receive an [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook. The next time you call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) , you will receive updated data.

If the refresh was not successful, you will receive a [INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED](https://plaid.com/docs/api/products/income/index.html.md#income_verification_refresh_reconnect_needed) webhook. To resolve this failure state, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . The refresh attempt will automatically be retried once the user has completed update mode, and an [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook will be sent if the retry is successful.

#### Download original documents 

To download PDF versions of the original payroll documents that were parsed to obtain payroll data, use the `document_metadata.download_url` returned by [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . Not all integrations will return a `download_url`.

In cases where an original source cannot be obtained, Plaid can optionally generate a PDF pay stub based on the data obtained. To enable Plaid-generated PDF pay stubs, contact your account manager. [View an example generated pay stub](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) .

#### Employment data 

Plaid provides employment data via the [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) endpoint. If you are on a Pay-as-you-go or Growth plan and want to use this endpoint, contact support to request access.

#### Testing Payroll Income 

[/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) can optionally be tested in Sandbox without using Link. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , pass the returned `user_token` to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) (use `ins_135842` when creating a public token for Payroll Income in Sandbox), and then call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . The output of [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) will not be used, but calling it initializes the user token for testing.

Payroll Income does not currently support the use of custom Sandbox data; only the default `user_good` user is compatible with Sandbox Payroll Income.

#### Payroll Income pricing 

Payroll Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . Payroll Income Refresh is billed on a [per-request fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Investments Move - Add Investments Move to your app | Plaid Docs

Add Investments Move to your app 
=================================

#### Use Investments Move to streamline brokerage-to-brokerage account transfers 

In this guide, we'll start from scratch and walk through how to use Investments Move to get the data required to set up an ACATS transfer. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to initialize Link with the `investments_auth` product; you can then skip ahead to [Fetching Investments Move data](https://plaid.com/docs/investments-move/add-to-app/index.html.md#fetching-investments-move-data) .

#### Get Plaid API keys and complete application profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.

First, on the client side of your application, you'll need to set up and configure Link. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

When initializing Link, you will need to specify the products you will be using in the product array.

##### Create a link\_token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['investments_auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

When using Investments Move, you can also configure options in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call to allow more brokerage accounts to be added, with the tradeoff that Plaid may not be able to verify all of the information. For details, see [Fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) .

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Fetching Investments Move data 

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. For more detailed information on the schema for account information returned, see [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) .

```javascript
const request: InvestmentsAuthGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.investmentsAuthGet(request);
  const investmentsAuthData = response.data;
} catch (error) {
  // handle error
}
```

The results of the [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) call return the information you need to submit an ACATS transfer, using verified data derived directly from the brokerage. Example response data is below. For more details on the schema of data returned, see the [API Reference](https://plaid.com/docs/api/products/investments-move/index.html.md#investments-auth-get-response-accounts) .

```json
{
  "accounts": [
    {
      "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ",
      "balances": {
        "available": 43200,
        "current": 43200,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "4444",
      "name": "Plaid Money Market",
      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
      "subtype": "money market",
      "type": "depository"
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "balances": {
        "available": null,
        "current": 320.76,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    }
  ],
  "holdings": [
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": "2021-05-25",
      "institution_price_datetime": null,
      "institution_value": 0.01,
      "iso_currency_code": "USD",
      "quantity": 0.01,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null,
      "vested_quantity": 1,
      "vested_value": 1
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 0.01,
      "institution_price": 0.011,
      "institution_price_as_of": "2021-05-25",
      "institution_price_datetime": null,
      "institution_value": 110,
      "iso_currency_code": "USD",
      "quantity": 10000,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "unofficial_currency_code": null,
      "vested_quantity": null,
      "vested_value": null
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "cost_basis": 40,
      "institution_price": 42.15,
      "institution_price_as_of": "2021-05-25",
      "institution_price_datetime": null,
      "institution_value": 210.75,
      "iso_currency_code": "USD",
      "quantity": 5,
      "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",
      "unofficial_currency_code": null,
      "vested_quantity": 7,
      "vested_value": 66
    }
  ],
  "item": {
    "available_products": [
      "assets",
      "balance",
      "beacon",
      "cra_base_report",
      "cra_income_insights",
      "signal",
      "identity",
      "identity_match",
      "income",
      "income_verification",
      "investments",
      "processor_identity",
      "recurring_transactions",
      "transactions"
    ],
    "billed_products": [
      "investments_auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_115616",
    "item_id": "7qBnDwLP3aIZkD7NKZ5ysk5X9xVxDWHg65oD5",
    "products": [
      "investments_auth"
    ],
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "numbers": {
    "acats": [
      {
        "account": "TR5555",
        "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
        "dtc_numbers": [
          "1111",
          "2222",
          "3333"
        ]
      }
    ]
  },
  "owners": [
    {
      "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ",
      "names": [
        "Alberta Bobbeth Charleson"
      ]
    },
    {
      "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy",
      "names": [
        "Alberta Bobbeth Charleson"
      ]
    }
  ],
  "request_id": "hPCXou4mm9Qwzzu",
  "securities": [
    {
      "close_price": 0.011,
      "close_price_as_of": null,
      "cusip": null,
      "industry": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "Nflx Feb 01'18 $355 Call",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": null,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "sedol": null,
      "ticker_symbol": "NFLX180201C00355000",
      "type": "derivative",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 9.08,
      "close_price_as_of": "2024-09-09",
      "cusip": null,
      "industry": "Investment Trusts or Mutual Funds",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "DoubleLine Total Return Bond I",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": "Miscellaneous",
      "security_id": "AE5rBXra1AuZLE34rkvvIyG8918m3wtRzElnJ",
      "sedol": "B5ND9B4",
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 42.15,
      "close_price_as_of": null,
      "cusip": null,
      "industry": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "iShares Inc MSCI Brazil",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": null,
      "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",
      "sedol": null,
      "ticker_symbol": "EWZ",
      "type": "etf",
      "unofficial_currency_code": null,
      "update_datetime": null
    },
    {
      "close_price": 1,
      "close_price_as_of": null,
      "cusip": null,
      "industry": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": true,
      "isin": null,
      "iso_currency_code": "USD",
      "market_identifier_code": null,
      "name": "U S Dollar",
      "option_contract": null,
      "proxy_security_id": null,
      "sector": null,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "sedol": null,
      "ticker_symbol": null,
      "type": "cash",
      "unofficial_currency_code": null,
      "update_datetime": null
    }
  ]
}
```

---


# Investments Move - Introduction to Investments Move | Plaid Docs

Introduction to Investments Move  
==================================

#### Automate ACATS and reduce rejections with broker-sourced data 

Get started with Investments Move

[API Reference](https://plaid.com/docs/api/products/investments-move/index.html.md)

#### Overview 

Investments Move (US and CA only) allows you to obtain broker-sourced data to automate brokerage account transfers, reduce operational complexity, and avoid rejections. You can use Investments Move to replace your existing manual ACATS data entry flow or build a new, high-performing flow. Investments Move is designed to increase both the number of users who submit an ACATS transfer and the rate at which these requests successfully settle.

Using Investments Move, a user accesses their brokerage account via a Plaid Link-initiated flow, and Plaid returns the source of truth data needed to submit an ACATS transfer, such as account number, account type, account holder name, holdings data, and DTC codes. For brokerages in Canada, Investments Move can retrieve the data necessary for an ATON transfer.

Investments Move is currently in Early Availability and available on a limited basis. To request access, if you are new to Plaid, [contact Sales](https://plaid.com/contact/) ; if you are already a Plaid customer, contact your Account Manager.

Looking for investment holdings or trading activity, without initiating ACATS transfers? See [Investments](https://plaid.com/docs/investments/index.html.md) instead.

#### Integration overview 

The steps below show an overview of how to integrate Investments Move.

1.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Along with any other parameters you specify, make sure to include the following:
    *   The `products` array should be set to `["investments_auth"]`.
    *   (Optional) To enable [fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) , set the corresponding flag within the `investments_auth` object. For details, see [Fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) .
2.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
3.  Once the end user has completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .
4.  Call the [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) endpoint with the `access_token` you received from the token exchange. This endpoint will return all the information needed to initiate an ACATS transfer, including account holder name, account number, and DTC number.

#### Fallback flows 

By default, an end user will only be able to select institutions where Plaid can obtain the full account number, account holder name, and holdings data. You can optionally choose to expand the number of institutions available by enabling one or more of the flows below, which allow the end user to directly enter data that Plaid was not able to obtain directly from the broker.

To know what data came directly from the brokerage, what was entered by the user and verified against partial data from the brokerage, and what was entered by the user but not verified by the brokerage because no data was available, you can use the `data_sources` object in the [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) response.

##### Masked Number Match 

Masked Number Match supports institutions where Plaid is able to obtain broker-sourced holdings data and account holder information but can only obtain a partial (masked) account number, typically the last four digits of the account number. During the Link flow, the user will be prompted to enter their full account number, which will be verified against the partial account number; if the numbers do not match, the Link attempt will fail and the user will be required to re-enter the account number.

To enable Masked Number Match, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, set `investments_auth.masked_number_match_enabled` to `true`.

##### Stated Account Number 

Stated Account Number supports institutions where Plaid is able to obtain broker-sourced holdings data, and may or may not be able to obtain account holder information, but cannot obtain any part of an account number. During the Link flow, the user will be prompted to enter their full account number. If Plaid was unable to obtain account holder information, the user will also be prompted to enter their full name.

To enable Stated Account Number, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, set `investments_auth.stated_account_number_enabled` to `true`.

##### Manual Entry 

Manual Entry supports institutions where Plaid cannot return any information. During the Link flow, users will be able to manually enter the information needed to submit the ACATS transfer. Plaid will still attempt to standardize and enrich the data they provide.

To enable Manual Entry, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, set `investments_auth.manual_entry_enabled` to `true`.

#### Testing Investments Move 

Investments Move can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) without any additional permissions.

To test fallback flows in Sandbox, use the institution Houndstooth Bank (`ins_109512`). The first fallback flow that is explicitly enabled in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call will be used. The flows will be attempted in the following order: Masked Number Match, Stated Account Number, and Manual Entry. (So for example, if both Masked Number Match and Manual Entry are enabled, Masked Number Match will be used.)

#### Investments Move pricing 

Investments Move is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . To view the exact pricing you may be eligible for, [contact Sales](https://plaid.com/contact/) .

---


# Investments - Add Investments to your app | Plaid Docs

Add Investments to your app 
============================

#### Learn how to add Investments endpoints to your application 

In this guide, we'll start from scratch and walk through how to use [Investments](https://plaid.com/docs/api/products/investments/index.html.md) to retrieve information on securities and holdings. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Fetching investment data](https://plaid.com/docs/investments/add-to-app/index.html.md#fetching-investment-data) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.

##### Create a link\_token 

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Fetching investment data 

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved investment data for an account, you can then use it to analyze data such as trading activity, net worth, and asset allocations.

Investments endpoints return two primary pieces of information about the investment account. The first is details on the holding itself (if using [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) ) or the transaction (if using [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) ). The second is details about the security itself. Each security, transaction, and holding contains a `security_id` field, which functions as a key for cross-referencing the holding or transaction with the security it pertains to. For more detailed information on the schema for information returned, see [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) .

Investments data is typically updated daily, after market close. To be alerted when new data is available to be retrieved, listen to [Investments webhooks](https://plaid.com/docs/api/products/investments/index.html.md#webhooks) .

##### Fetching investment holdings 

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { InvestmentsHoldingsGetRequest } = require('plaid');


// Pull Holdings for an Item
const request: InvestmentsHoldingsGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.investmentsHoldingsGet(request);
  const holdings = response.data.holdings;
  const securities = response.data.securities;
} catch (error) {
  // handle error
}
```

Example response data is below.

```json
{
  "accounts": [
    {
      "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",
      "balances": {
        "available": 43200,
        "current": 43200,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "4444",
      "name": "Plaid Money Market",
      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
      "subtype": "money market",
      "type": "depository"
    },
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "balances": {
        "available": null,
        "current": 320.76,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    }
  ],
  "holdings": [
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 0.01,
      "institution_price": 0.011,
      "institution_price_as_of": null,
      "institution_value": 110,
      "iso_currency_code": "USD",
      "quantity": 10000,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 23,
      "institution_price": 27,
      "institution_price_as_of": null,
      "institution_value": 636.309,
      "iso_currency_code": "USD",
      "quantity": 23.567,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "unofficial_currency_code": null
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "credit_details",
      "identity",
      "investments",
      "liabilities",
      "transactions"
    ],
    "billed_products": ["assets", "auth", "investments"],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "l68wb8zpS0hqmsJ",
  "securities": [
    {
      "close_price": 0.011,
      "close_price_as_of": null,
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "Nflx Feb 01'18 $355 Call",
      "proxy_security_id": null,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "sedol": null,
      "ticker_symbol": "NFLX180201C00355000",
      "type": "derivative",
      "unofficial_currency_code": null,
      "market_identifier_code": "XNAS",
      "option_contract": {
        "contract_type": "call",
        "expiration_date": "2018-02-01",
        "strike_price": 355.00,
        "underlying_security_ticker": "NFLX"
      }
    },
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "unofficial_currency_code": null,
      "market_identifier_code": "XNAS",
      "option_contract": null
    }
  ]
}
```

##### Fetching investment transactions 

Select group for content switcher

Current librariesLegacy libraries

```javascript
const request: InvestmentsTransactionsGetRequest = {
  access_token: accessToken,
  start_date: '2019-01-01',
  end_date: '2019-06-10',
  options: {
    count: 250,
    offset: 0,
  },
};
try {
  const response = await plaidClient.investmentsTransactionsGet(request);
  const investmentTransactions = response.data.investment_transactions;
} catch (error) {
  // handle error
}
```

Sample response data is below.

```json
{
  "accounts": [
    {
      "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",
      "balances": {
        "available": null,
        "current": 320.76,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    }
  ],
  "investment_transactions": [
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -8.72,
      "cancel_transaction_id": null,
      "date": "2020-05-29",
      "fees": 0,
      "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
      "iso_currency_code": "USD",
      "name": "INCOME DIV DIVIDEND RECEIVED",
      "price": 0,
      "quantity": 0,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "subtype": "dividend",
      "type": "cash",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -1289.01,
      "cancel_transaction_id": null,
      "date": "2020-05-28",
      "fees": 7.99,
      "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
      "iso_currency_code": "USD",
      "name": "SELL Matthews Pacific Tiger Fund Insti Class",
      "price": 27.53,
      "quantity": -47.74104242992852,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "subtype": "sell",
      "type": "sell",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": 7.7,
      "cancel_transaction_id": null,
      "date": "2020-05-27",
      "fees": 7.99,
      "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",
      "iso_currency_code": "USD",
      "name": "BUY DoubleLine Total Return Bond Fund",
      "price": 10.42,
      "quantity": 0.7388014749727547,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "subtype": "buy",
      "type": "buy",
      "unofficial_currency_code": null
    }
  ],
  "item": {
    "available_products": ["assets", "balance", "identity", "transactions"],
    "billed_products": ["auth", "investments"],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_12",
    "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "iv4q3ZlytOOthkv",
  "securities": [
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "unofficial_currency_code": null,
      "market_identifier_code": "XNAS",
      "option_contract": null
    },
    {
      "close_price": 10.42,
      "close_price_as_of": null,
      "cusip": "258620103",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US2586201038",
      "iso_currency_code": "USD",
      "name": "DoubleLine Total Return Bond Fund",
      "proxy_security_id": null,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "sedol": null,
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "unofficial_currency_code": null,
      "market_identifier_code": "XNAS",
      "option_contract": null
    }
  ],
  "total_investment_transactions": 2
}
```

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Investments - Introduction to Investments | Plaid Docs

Introduction to Investments  
=============================

#### View holdings and transactions from investment accounts 

Get started with Investments

[API Reference](https://plaid.com/docs/api/products/investments/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md)

#### Overview 

The Investments product allows you to obtain holding, security, and transactions data for investment-type accounts in financial institutions within the United States and Canada. This data can be used for personal financial management tools and wealth management analysis.

Looking for Plaid's solution to automate ACATS transfers and avoid friction, failures, and delays due to manual data entry? See [Investments Move](https://plaid.com/docs/investments-move/index.html.md) instead.

[Prefer to learn by watching? Get an overview of how Investments works in just 3 minutes!](https://www.youtube.com/watch?v=DYiKaQgYJ74)

#### Securities and holdings 

The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) endpoint provides both security data and holding data. Security data represents information about a specific security, such as its name, ticker symbol, and price. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data.

```json
{
  "close_price": 10.42,
  "close_price_as_of": null,
  "cusip": "258620103",
  "institution_id": null,
  "institution_security_id": null,
  "is_cash_equivalent": false,
  "isin": "US2586201038",
  "iso_currency_code": "USD",
  "name": "DoubleLine Total Return Bond Fund",
  "proxy_security_id": null,
  "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
  "sedol": null,
  "ticker_symbol": "DBLTX",
  "type": "mutual fund",
  "unofficial_currency_code": null,
  "market_identifier_code": "XNAS",
  "option_contract": null
}
```

Holding data, by contrast, represents information about a user's specific ownership of that security, such as the number of shares owned and the cost basis. Each holding includes a `security_id` field that can be cross-referenced to a security for more detailed information about the security itself.

```json
{
  "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
  "cost_basis": 10,
  "institution_price": 10.42,
  "institution_price_as_of": null,
  "institution_value": 20.84,
  "iso_currency_code": "USD",
  "quantity": 2,
  "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
  "unofficial_currency_code": null
}
```

#### Transactions 

The [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint provides up to 24 months of investment transactions data. The schema for investment transactions is not the same as for transactions data returned by the [Transactions](https://plaid.com/docs/transactions/index.html.md) product, instead providing securities-specific information. Inflow, such as stock sales, is shown as a negative amount, and outflow, such as stock purchases, is positive. The [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint can only be used for investment-type accounts; for obtaining transaction history for other account types, use [Transactions](https://plaid.com/docs/transactions/index.html.md) .

```json
{
  "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
  "amount": -8.72,
  "cancel_transaction_id": null,
  "date": "2020-05-29",
  "fees": 0,
  "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
  "iso_currency_code": "USD",
  "name": "INCOME DIV DIVIDEND RECEIVED",
  "price": 0,
  "quantity": 0,
  "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
  "subtype": "dividend",
  "type": "cash",
  "unofficial_currency_code": null
}
```

#### Investments transactions initialization behavior 

Unlike the Transactions product, Investments Transactions operates synchronously by default and will not fire a webhook to indicate when initial data is ready for an Item. If investments transactions data is not ready when [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) is first called, Plaid will wait for the data. For this reason, calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) immediately after Link may take up to one to two minutes to return.

If you are adding Investments to an Item by calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) [after the Item was originally linked](https://plaid.com/docs/link/initializing-products/index.html.md#adding-products-post-link) , instead of specifying the Investments product while calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you can optionally request asynchronous behavior by specifying `async_update=true`. In this case, Investments will fire a [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-historical_update) webhook when data is ready to be fetched. In all other scenarios, Investments endpoints will operate synchronously and will not fire a webhook to indicate when the Item's initial data is available to be fetched.

#### Investments updates and webhooks 

Investments data is not static, since users' holdings will change as they trade and as market prices fluctuate. Plaid typically checks for updates to investment data overnight, after market hours. You can also request an update on-demand via the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint, which is available as an add-on for Investments customers. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/settings/team/products) or contact your Plaid account manager.

There are two webhooks that are used for informing you of changes to investment data. The [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#holdings-default_update) webhook of type `HOLDINGS` fires when new holdings have been detected or the quantity or price of an existing holding has changed. The [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-default_update) webhook of type `INVESTMENTS_TRANSACTIONS` fires when a new or canceled investment transaction has been detected.

When updating an Item with new Investments transactions data, it is recommended to call [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) with only the date range that needs to be updated, rather than the maximum available date range, in order to reduce the amount of data that you must receive and process.

#### Investments institution coverage 

By default, Investments provides access to data at over 2,400 institutions in the US and Canada.

Access to Fidelity Investments is available upon request. To request access, contact your Plaid Account Manager.

#### Testing Investments 

Investments can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) without any additional permissions.

To test with realistic data, use the [custom user](https://github.com/plaid/sandbox-custom-users) . If provided real-world ticker symbols, Plaid will automatically populate securities with realistic data for both options and contracts. For examples, see the [sample Investments custom user](https://github.com/plaid/sandbox-custom-users/blob/main/investments/brokerage_custom_user.json) .

When using the custom Sandbox user, Investments must be placed in the `products` array of [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and cannot be used in the `optional_products`, `additional_consented_products`, or `required_if_supported_products` array. Omitting `investments` from the `products` array may cause custom Sandbox investments data not to be loaded.

#### Investments pricing 

Investments is billed on a [subscription model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) ; Investments Refresh is billed on a [per-request flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

To get started building with Investments, see [Add Investments to your App](https://plaid.com/docs/investments/add-to-app/index.html.md) .

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# KYC/AML and anti-fraud | Plaid Docs

KYC, AML, and anti-fraud products 
==================================

#### Review and compare solutions 

This page provides overviews of Plaid's KYC, AML, and anti-fraud products to help you find the right one for your needs.

Plaid offers Identity Verification for KYC (Know Your Customer) compliance, Monitor for AML (Anti Money Laundering) compliance, and Beacon (beta) for anti-fraud. The three products are tightly integrated and managed through a single dashboard but can also be used separately.

Plaid Identity is also an anti-fraud solution targeted specifically at account takeover fraud. Because it's designed for payments use cases, you can learn more about it on the [Payments products](https://plaid.com/docs/payments/index.html.md) page.

#### Identity Verification 

[Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) is Plaid's KYC solution. Via an interactive session with the user, Identify Verification allows you to check user-provided identity information such as name, ID number, phone number, and address against high-trust identity databases; check identity documents for expiration, signs of fraud, or mismatch with other user-provided data; run selfie verification to confirm liveness and photo ID matching; verify a user's phone number via SMS; and analyze a user's session, behavior, and identity details for signs of fraud. Identity Verification can also be run as a fully background session without interactivity (for checking pre-collected user data against databases only). Identity Verification can plug directly into Monitor for automatic AML watchlist scanning.

Identity Verification is a separate product from Identity / Identity Match, but can integrate directly with [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) to reduce account takeover fraud risk when a user has linked a financial account to your application. Identity Match will verify that the ownership details (such as name, address, and phone number) on the linked account match the data verified via Identity Verification.

#### Monitor 

[Monitor](https://plaid.com/docs/monitor/index.html.md) provides AML capabilities, screening users against PEP (Politically Exposed Person) and sanction lists. Monitor is frequently used with Identity Verification -- integrating Monitor into an existing Identity Verification deployment can be as simple as checking a box on your Identity Verification template -- but can also be deployed separately. Any watchlist hits will be exposed via both a user-friendly dashboard UI and via API, for use with either manual or automated review workflows.

#### Monitor and Identity Verification comparison 

|  | Identity Verification | Monitor |
| --- | --- | --- |
| Summary | Flexible and configurable KYC compliance to verify identity and detect fraud | Scan users against watchlists for AML compliance |
| Supported countries | 190+ countries | 190+ countries |
| UI languages | English, French, Spanish, Japanese, Portuguese | N/A |
| Billing plans available | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract |

##### Beacon 

Beacon is Plaid's free network for fraud detection. You can scan all new users with Beacon to see whether they have any known fraud alerts from the Beacon Network. You can also be alerted when a new incident of fraud is reported on a user you have already added. These capabilities are available free of charge to all Plaid customers.

---


# Launch checklist | Plaid Docs

Launch in Production checklist 
===============================

#### Check off these recommended steps before launching your app in Production 

The Launch Checklist has been replaced by the [Launch Center](https://dashboard.plaid.com/developers/launch-center) . The Launch Center shows a personalized list of steps for your integration, with links to supporting materials like videos, sample code, and docs. The Launch Checklist is no longer being updated.

Below is a list of recommended steps to take before launching your Plaid integration in production. While they might not all be required for the minimal operation of your application, the steps below will help to make your Plaid integration more robust, secure, efficient, and maintainable.

For a similar list of steps in a PDF guide format, see the [Plaid implementation handbook](https://plaid.com/documents/plaid-implementation-handbook.pdf) .

#### Production setup 

#### Link setup 

Follow the steps below to assist users in completing the Link flow, help ensure compliance with Plaid's policies, and avoid being billed for unneeded products.

You may find it helpful to know that some of our customers link to Plaid's privacy policy within their own privacy policy, while others surface a separate just-in-time notice and consent page during their onboarding flow. Ultimately, it is up to you to determine how to obtain any legally required consents.

##### Callbacks 

Handle callbacks beyond just `onSuccess` in order to gracefully handle errors and build analytics around Link.

#### Webhook configuration 

Plaid uses webhooks for many common flows. If your integration does any of the following, webhooks are required or strongly recommended:

*   (Any product) Your application is calling a Plaid endpoint for an Item repeatedly, over a period of time, not just immediately after Link.
*   (Transactions or Investments) You are accessing transactions made after the end user linked their Item.
*   (Auth) You are using automated micro-deposits for account verification, or making transfers over a year after the Item was initially linked.
*   (Assets) You are creating Asset Reports.
*   (Income) You are verifying a user's income.
*   (Payment Initiation (UK and Europe)) You are initiating payments.
*   (Virtual Accounts (UK and Europe) or Transfer) You are sending or receiving funds.

#### Error handling 

#### Link in update mode 

Update mode is used to fix Items that have entered an error state (for example, because a user changed their password). If your application needs to access an Item repeatedly over a period of time, rather than just immediately after Link, implementing update mode logic is strongly recommended.

#### Storage & logging 

Log Plaid identifiers and IDs properly to enhance security, when contacting Support about a specific request or callback, and for finding specific entries in the [Activity Log](https://dashboard.plaid.com/activity/logs) . For more information, see [Dashboard logs and troubleshooting](https://plaid.com/docs/account/activity/index.html.md) .

Ensure that the following identifiers are securely logged, as they will be needed when contacting Support about a specific request or callback.

#### Item management 

#### Multi-app use cases 

### Product-specific recommendations 

#### Auth 

If you are using Auth for an account funding use case, see the [Plaid account funding guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for use case specific recommendations.

#### Balance 

If you are using Balance for an account funding use case, see the [Plaid account funding guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for use case specific recommendations.

#### Identity 

If you are using Identity for an account funding use case, see the [Plaid account funding guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for use case specific recommendations.

#### Transactions 

#### Investments 

#### Assets 

#### Payment Initiation 

#### Virtual Accounts 

#### Income 

See the [Plaid income verification solution guide](https://plaid.com/documents/plaid-income-verification-solution-guide.pdf) for use case specific recommendations.

#### Identity Verification 

See the [Plaid Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf) for use case specific recommendations.

#### Monitor 

See the [Plaid Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf) for use case specific recommendations.

---


# Layer - Add Layer to your app | Plaid Docs

Layer integration guide 
========================

#### Use Layer to instantly onboard new customers 

In this guide, we'll start from scratch and walk through how to use [Layer](https://plaid.com/docs/api/products/layer/index.html.md) to create a fast, frictionless onboarding experience for your customers.

If you're already familiar with Link, you can skip to [Create a Link token](https://plaid.com/docs/layer/add-to-app/index.html.md#create-a-link-token) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) .

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Launch Link 

Plaid Link is a drop-in module that provides a secure, elegant flow for Layer. Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.

##### Create a Link token 

Unlike a regular Link flow, the starting point for Layer is a call to [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) with a specified `TEMPLATE_ID`. The template should be created and configured in the dashboard ahead of time. If you want to use other products in addition to the `layer` product, make sure your template has them enabled.

```javascript
app.post('/api/create_session_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    template_id: TEMPLATE_ID,
  };
  try {
    const createTokenResponse = await client.sessionTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install the Link SDKs 

For instructions on installing Link SDKs, see the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform: [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , or [React](https://plaid.com/docs/link/web/index.html.md) . Layer is not supported on mobile webview integrations.

As Plaid is actively adding new Layer functionality, it is strongly recommended that you use the latest SDK version if your app uses Layer.

If you are developing a native mobile application, Layer requires SDK versions from June 2024 or later. Minimum versions are 6.0.4 (iOS), 4.5.0 (Android), and 11.11.0 (React Native). For Extended Autofill support, minimum versions are 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React).

Layer is not compatible with the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration mode.

##### Create the Link Handler 

Basic sample code for creating the Link handler is shown below. For more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform: [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , or [React](https://plaid.com/docs/link/web/index.html.md) .

Ensure you are creating a Link token and passing it to the Link SDK as early as possible. The more time between when you create your handler and when you open Link, the better the UX will be for your users.

If you already have an existing Android or React Native integration created prior to June 2024, you will likely need to update your client-side Link opening code to support Layer. If your Android integration does not use a `PlaidHandler` or uses `OpenPlaidLink` instead of `FastOpenPlaidLink`, or if your React Native integration uses `PlaidLink` instead of `create` and `open`, you will need to add a separate handler creation step, as shown in the sample code below. For more details, see [React Native: opening Link](https://plaid.com/docs/link/react-native/index.html.md#opening-link) and [Android: opening Link](https://plaid.com/docs/link/android/index.html.md#create-a-linktokenconfiguration) .

Select group for content switcher

AndroidiOSReact NativeWeb

##### Create a LinkTokenConfiguration 

Each time you open Link, you will need to get a new `link_token` from your server and create a new `LinkTokenConfiguration` object with it.

```typescript
val linkTokenConfiguration = linkTokenConfiguration {
  token = "LINK_TOKEN_FROM_SERVER"
}
```

The Link SDK runs as a separate `Activity` within your app. In order to return the result to your app, it supports both the standard `startActivityForResult` and `onActivityResult` and the `ActivityResultContract` [result APIs](https://developer.android.com/training/basics/intents/result) .

Select group for content switcher

Activity Result APIsStandard Activity APIs

##### Register a callback for an Activity Result 

```typescript
private val linkAccountToPlaid =
registerForActivityResult(FastOpenPlaidLink()) {
  when (it) {
    is LinkSuccess -> /* handle LinkSuccess */
    is LinkExit -> /* handle LinkExit */
  }
}
```

##### Create a PlaidHandler 

```typescript
val plaidHandler: PlaidHandler = 
  Plaid.create(application, linkTokenConfiguration)
```

##### Open Link 

```typescript
linkAccountToPlaid.launch(plaidHandler)
```

##### Create a Configuration 

Once the Link token is passed to your app, you will create an instance of `LinkTokenConfiguration`, then create a Handler using `Plaid.create()` passing the previously created `LinkTokenConfiguration`.

```clike
var linkConfiguration = LinkTokenConfiguration(
    token: "<#LINK_TOKEN_FROM_SERVER#>",
    onSuccess: { linkSuccess in
        // Send the linkSuccess.publicToken to your app server.
    }
)
```

##### Create a Handler 

A `Handler` is a one-time use object used to open a Link session. The `Handler` must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link redirects. For more details, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md#ios) .

```clike
let result = Plaid.create(configuration)
switch result {
  case .failure(let error):
      logger.error("Unable to create Plaid handler due to: \(error)")
  case .success(let handler):
      self.handler = handler
}
```

Initiate the Link preloading process by invoking the `create` function.

```javascript
 {
      create({token: linkToken});
      setDisabled(false);
    }
  }>
  Create Link

```

Call `Plaid.create` (or, if using React, `usePlaidLink`) when initializing the view that is responsible for loading Plaid.

```tsx
// The usePlaidLink hook manages Plaid Link creation
// It does not return a destroy function;
// instead, on unmount it automatically destroys the Link instance
const config: PlaidLinkOptions = {
  onSuccess: (public_token, metadata) => {}
  onExit: (err, metadata) => {}
  onEvent: (eventName, metadata) => {}
  token: 'GENERATED_LINK_TOKEN',
};


const { open, exit, ready, submit } = usePlaidLink(config);
```

#### Submit the user’s phone number 

Call the `submit` method on the Plaid handler you created earlier with the user's phone number. The semantics depend on the language/platform, but all methods are called `submit`.

Select group for content switcher

AndroidiOSReact NativeWeb

```typescript
val submissionData = SubmissionData(phoneNumber)
plaidHandler.submit(submissionData)
```

```clike
// Create a model that conforms to the SubmissionData interface
struct PlaidSubmitData: SubmissionData {
    var phoneNumber: String?
}


let data = PlaidSubmitData(phoneNumber: "14155550015")


self.handler.submit(data)
```

```javascript
submit({
  "phone_number": "+14155550123"
})
```

```javascript
handler.submit({
  "phone_number": "+14155550123"
})
```

#### Submit the user's date of birth 

Upon receiving `LAYER_NOT_AVAILABLE` after phone number submission, collect the user's date of birth and call the `submit` method on the existing Plaid handler. For more details, see [Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) .

This functionality requires minimum SDK versions 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React). If you are using an older SDK version or do not wish to use Extended Autofill, you can skip this step.

Select group for content switcher

AndroidiOSReact NativeWeb

```typescript
val submissionData = SubmissionData(dateOfBirth = "1975-01-18")
plaidHandler.submit(submissionData)
```

```clike
// Create a model that conforms to the SubmissionData interface
struct PlaidSubmitData: SubmissionData {
    var dateOfBirth: String?
    var phoneNumber: String?
}


let data = PlaidSubmitData(dateOfBirth: "1975-01-18")


self.handler.submit(data)
```

```javascript
submit({
  "dateOfBirth": "1975-01-18"
})
```

```javascript
handler.submit({
  "date_of_birth": "1975-01-18"
})
```

#### Open Layer UI on the LAYER\_READY event 

Listen to the events on the Plaid handler via `onEvent`. For platform-specific details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform.

If you receive `LAYER_READY`, the user is eligible for the Layer flow and you should proceed to open Link according to the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform.

If you receive `LAYER_AUTOFILL_NOT_AVAILABLE` (or if you receive `LAYER_NOT_AVAILABLE` and have not built Extended Autofill support for your integration), the user is not eligible for the Layer flow. You can clean up the handler you created earlier and fall back to whatever non-Layer onboarding flow fits your application (e.g. a traditional Link session, or other custom flow for your app).

Select group for content switcher

AndroidiOSReact NativeWeb

```typescript
Plaid.setLinkEventListener { event ->
    when(event.eventName) {
    is LAYER_READY -> {
    // open link
      linkAccountToPlaid.launch(plaidHandler)
    }
    is LAYER_NOT_AVAILABLE -> {
      // run fall back flow
    }
    else -> { Log.i("Event", event.toString()) }
}
```

```clike
var linkSessionID: String?


linkTokenConfiguration.onEvent = { [weak self] linkEvent in
    guard let self = self else { return }
    switch linkEvent.eventName {
        case .layerReady:
            self.handler.open(presentUsing: .viewController(self))
            break
        case .layerNotAvailable:
            // Fall back on non-Layer flows, clean up
            break
        default:
            // Other cases ignored in this use case.
            break
    }
}
```

```javascript
usePlaidEmitter((event: LinkEvent) => {
  switch (event.eventName) {
    case LinkEventName.LAYER_READY:
      // Open Link
      open({...})
      break;
    case LinkEventName.LAYER_NOT_AVAILABLE:
      // Run another fallback flow
      break;
    default:
      // Other cases ignored in this use case
      break;
  }
});
```

```javascript
//Same onEvent handler from Link create sample
onEvent: (eventName, metadata) => {
  switch(eventName) {
    case "LAYER_READY":
      // Open Link
      open({...})
      break;
  case "LAYER_NOT_AVAILABLE":
    // Run another fallback flow
    break;
  default:
    //Other cases ignored in this use case
    break;
}
```

#### Get the public token from the onSuccess callback 

On successful completion, an `onSuccess` callback will be invoked, similar to the standard Link flow. Capture the `public_token` from `onSuccess`.

Select group for content switcher

AndroidiOSReact NativeWeb

```typescript
val profileToken = success.publicToken
// Send the public token to your backend
```

```clike
onSuccess: { linkSuccess in
}
// Send the public token to your backend
```

```javascript
const onSuccess = (success: LinkSuccess) => {
  let publicToken =  linkSuccess.publicToken
  // Send the public token to your backend
};
```

```javascript
onSuccess: (public_token) => {
  const publicToken = public_token
  // Send the public token to your backend
};
```

#### Get user account data 

Call [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) to retrieve user-permissioned identity information as well as Item access tokens. Unlike typical Plaid Link sessions, where you must first exchange your public token for an access token in order to talk to the Plaid API, the [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) endpoint allows you to retrieve user-permissioned identity information as well as Item access tokens in a single call.

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

```json
{
  "identity": {
    "phone_number": "+14155550015"
    "name": {
      "first_name": "Leslie",
      "last_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Apt 123",
      "city": "Pawnee",
      "region": "Indiana",
      "postal_code": "46001",
      "country": "US"
    },
    "email": "leslie@knope.com",
    "date_of_birth": "1979-01-01",
    "ssn": "987654321",
    "ssn_last4": "4321"
  },
  "items": [
    {
      "item_id": ,
      "access_token": "access-token-",
    }
  ],
  "request_id": "j0LkqT9OPdVwjwh"
}
```

---


# Layer - Introduction to Layer | Plaid Docs

Introduction to Layer  
=======================

#### Onboard users instantly with just a phone number 

Get started with Layer

[API Reference](https://plaid.com/docs/api/products/layer/index.html.md) [Request Access](https://plaid.com/layer/#contact-form) [Demo](https://plaid.coastdemo.com/share/6717daecf618361b93d583f5?zoom=100)

#### Overview 

Instantly onboard millions of people from the Plaid Network with Layer (US only).

Given a phone number, we can find out if that person is on the Plaid Network and if they meet your onboarding requirements. Next, we authenticate the device and use real-time risk analysis to securely deliver the fastest user experience. Once they confirm their details and choose which financial account to share, you can verify their identity using your KYC provider and connect their accounts with Plaid.

The user enters their phone number within your application.

(An image of "The user enters their phone number within your application.")

(An image of "Plaid determines the user is eligible for Layer, so they are prompted to continue with Plaid.")

(An image of "The user's device is authenticated...")

(An image of "...and the user chooses what information to share with your application.")

(An image of "And we're done! You're now able to retrieve user account data.")

To get started with Layer, [contact Sales](https://plaid.com/layer/#contact-form) to request Sandbox access.

[See a live, interactive demo](https://plaid.coastdemo.com/share/6717daecf618361b93d583f5?zoom=100) of a Plaid-powered onboarding flow using Layer.

#### Integration overview 

If you use Layer with Plaid Check products, see the Plaid Check [Layer onboarding guide](https://plaid.com/docs/check/onboard-users-with-layer/index.html.md) .

For a video walkthrough, you can also watch the following guide.

[Watch video](https://www.youtube.com/watch?v=verarxGD8G0)

1.  Configure a Layer template via the [dashboard](https://dashboard.plaid.com/layer) . A template is created by default on first visit. You can customize the template's name, set logo and colors to match your brand, and configure eligibility requirements. In general, fill rates for different user data fields are highly correlated with each other (i.e., if Plaid has access to one piece of user identity information, it very likely has access to all of them), so you should set "required" and "optional" eligibility requirements based on your true business needs.
    
2.  Call [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) with the template ID for the Layer template you configured. This will return a `link` object that contains a `link_token`.
    
3.  On your client, create an instance of Link using the `link.link_token` string returned by [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) . With Layer, you should create the Plaid handler object (i.e. via `Plaid.create(...)`) as early as possible so Link can pre-load in the background. This ensures the fastest possible experience for your users.
    
    If you have an existing Android integration that does not use a `PlaidHandler` or that uses `OpenPlaidLink` instead of `FastOpenPlaidLink`, or an existing React Native integration that uses `PlaidLink` instead of `create` and `open`, you will need to update your client-side Link opening code to take advantage of the new faster loading scheme. For details and sample code, see [React Native: opening Link](https://plaid.com/docs/link/react-native/index.html.md#opening-link) and [Android: opening Link](https://plaid.com/docs/link/android/index.html.md#create-a-linktokenconfiguration) .
    
4.  Once you have a user's phone number, pass it to the Plaid handler object: `handler.submit({ "phone_number": "+14155550015"})`. Link will quickly check if the user is eligible for Layer, and call the Link `onEvent` callback with either `LAYER_READY` or `LAYER_NOT_AVAILABLE`. Note that if the phone number uses a country code other than +1, the result will always be `LAYER_NOT_AVAILABLE`, as Layer does not support international phone numbers.
    
5.  When you receive `LAYER_READY`, it means the user is eligible and you should call `handler.open()` to immediately present the Layer UI.
    
6.  (Optional, recommended) If you receive `LAYER_NOT_AVAILABLE` instead, collect the user's date of birth and `submit` it via the same handler as earlier, e.g. `handler.submit({ "date_of_birth": "1975-01-18"})`. If you receive `LAYER_READY`, the user is eligible for [Layer Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) and you should call `handler.open()` to immediately present the Layer UI. If you receive `LAYER_AUTOFILL_NOT_AVAILABLE`, proceed to the next step.
    
7.  If neither Layer nor Layer Extended Autofill are available, you may discard the handler object and continue with any non-Layer flow in your app. For example, if your application falls back to a non-Layer product flow, you'd create a new Link Token and handler to present that flow.
    
8.  Once the end user has completed the Link flow, you will receive an `onSuccess` callback. Use the received `public_token` with the [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) API in order to retrieve the user's profile information and any linked Items.
    

#### Sample code 

For a walkthrough of integrating Layer, including sample code across multiple platforms, see [Add Layer to your app](https://plaid.com/docs/layer/add-to-app/index.html.md) .

#### Minimum SDK versions 

As Plaid is actively adding new Layer functionality, it is strongly recommended that you use the latest SDK version and keep up to date with SDK updates if your app uses Layer.

If you are developing for the web using the JavaScript SDK, Plaid will automatically provide the latest available SDK. Otherwise, see [libraries](https://plaid.com/docs/api/libraries/index.html.md#link-client-sdks) for links to the latest SDKs.

If you are developing a native mobile application, Layer requires SDK versions from June 2024 or later. Minimum versions are 6.0.4 (iOS), 4.5.0 (Android), 11.11.0 (React Native), and 3.5.2 (React). For Autofill support, minimum versions are 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React).

Layer is not compatible with the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration mode.

#### Extended Autofill 

Extended Autofill allows you to use the user's date of birth as a fallback for autofilling their identity data if their phone number is not Layer eligible. For Extended Autofill support, minimum SDK versions are 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React).

To use Extended Autofill, after receiving `LAYER_NOT_AVAILABLE`, submit the date of birth, e.g. `handler.submit({ "date_of_birth": "1975-01-18"})`. You will get either a `LAYER_READY` callback (success) or a `LAYER_AUTOFILL_NOT_AVAILABLE` callback (failure).

When using Extended Autofill, in order to reduce onboarding friction, it is strongly recommended to prompt the user for their date of birth only after receiving `LAYER_NOT_AVAILABLE`, rather than requesting it upfront.

#### Testing Layer 

In Sandbox, the authentication code for all phone numbers is `123456`. The basic test phone number is `415-555-0015`. The date of birth (for Extended Autofill testing) is `1975-01-18`. The following phone numbers are all valid in Sandbox for Layer testing:

| Phone number | Notes |
| --- | --- |
| 415-555-0\[0-9\]15 | Standard profiles with full PII |
| 515-555-0011 | Missing last name |
| 515-555-0013 | Missing email |
| 515-555-0015 | Missing DOB |
| 515-555-0016 | Missing SSN |
| 515-555-0017 | Missing address |
| 515-555-0018 | Missing name |

To test Extended Autofill, submit any phone number that fails Layer eligibility, like `+14155550000`.

In Production, the authentication step of Layer is dynamic and may authenticate the user via Silent Network Authentication, SMS OTP, or Passkeys (coming soon), depending on the user and the device; authentication checks such as trusted device matching or mobile carrier checks (for SIM swaps, port outs, etc.) are also run in Production.

Sandbox provides a simplified authentication experience: in Sandbox, users can only be authenticated via OTP, and authentication checks are not run.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Liabilities - Add Liabilities to your app | Plaid Docs

Add Liabilities to your app 
============================

#### Use Liabilities to fetch data for credit, student loan, and mortgage accounts 

In this guide, we'll start from scratch and walk through how to use Liabilities to retrieve information about credit card, PayPal credit, student loan, and mortgage accounts. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to initialize Link with the `liabilities` product and to note that Liabilities supports the use of [account subtype filtering](https://plaid.com/docs/liabilities/add-to-app/index.html.md#create-an-item-in-link) ; you can then skip ahead to [Fetching Liabilities data](https://plaid.com/docs/liabilities/add-to-app/index.html.md#fetching-liabilities-data) .

#### Get Plaid API keys and complete application profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.

First, on the client side of your application, you'll need to set up and configure Link. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

When initializing Link, you will need to specify the products you will be using in the product array.

Liabilities supports the use of the `account_filters` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , which you can use to limit the account types that will be shown in Link to either only credit card accounts, only student loan accounts, or only mortgage accounts. For student loans, use the type `loan` and subtype `student`. For credit cards, use the type `credit` and subtype `credit card`. For mortgages, use the type `loan` and subtype `mortgage`.

##### Create a link\_token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['liabilities'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Fetching Liabilities data 

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. For more detailed information on the schema for account information returned, see [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { LiabilitiesGetRequest } = require('plaid');


// Retrieve Liabilities data for an Item
const request: LiabilitiesGetRequest = {
  access_token: accessToken,
};
try {
  const response = await plaidClient.liabilitiesGet(request);
  const liabilities = response.data.liabilities;
} catch (error) {
  // handle error
}
```

Example response data is below. The data provided is for illustrative purposes; in a Production environment, it would be very unusual for a single institution to provide both credit card and student loan data.

```json
{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "balances": {
        "available": null,
        "current": 410,
        "iso_currency_code": "USD",
        "limit": 2000,
        "unofficial_currency_code": null
      },
      "mask": "3333",
      "name": "Plaid Credit Card",
      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
      "subtype": "credit card",
      "type": "credit"
    },
    {
      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    },
    {
      "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
      "balances": {
        "available": null,
        "current": 56302.06,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "8888",
      "name": "Plaid Mortgage",
      "official_name": null,
      "subtype": "mortgage",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": ["balance", "credit_details", "investments"],
    "billed_products": [
      "assets",
      "auth",
      "identity",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "liabilities": {
    "credit": [
      {
        "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
        "aprs": [
          {
            "apr_percentage": 15.24,
            "apr_type": "balance_transfer_apr",
            "balance_subject_to_apr": 1562.32,
            "interest_charge_amount": 130.22
          },
          {
            "apr_percentage": 27.95,
            "apr_type": "cash_apr",
            "balance_subject_to_apr": 56.22,
            "interest_charge_amount": 14.81
          },
          {
            "apr_percentage": 12.5,
            "apr_type": "purchase_apr",
            "balance_subject_to_apr": 157.01,
            "interest_charge_amount": 25.66
          },
          {
            "apr_percentage": 0,
            "apr_type": "special",
            "balance_subject_to_apr": 1000,
            "interest_charge_amount": 0
          }
        ],
        "is_overdue": false,
        "last_payment_amount": 168.25,
        "last_payment_date": "2019-05-22",
        "last_statement_issue_date": "2019-05-28",
        "last_statement_balance": 1708.77,
        "minimum_payment_amount": 20,
        "next_payment_due_date": "2020-05-28"
      }
    ],
    "mortgage": [
      {
        "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
        "account_number": "3120194154",
        "current_late_fee": 25.0,
        "escrow_balance": 3141.54,
        "has_pmi": true,
        "has_prepayment_penalty": true,
        "interest_rate": {
          "percentage": 3.99,
          "type": "fixed",
        },
        "last_payment_amount": 3141.54,
        "last_payment_date": "2019-08-01",
        "loan_term": "30 year",
        "loan_type_description": "conventional",
        "maturity_date": "2045-07-31",
        "next_monthly_payment": 3141.54,
        "next_payment_due_date": "2019-11-15",
        "origination_date": "2015-08-01",
        "origination_principal_amount": 425000,
        "past_due_amount": 2304,
        "property_address": {
          "city": "Malakoff",
          "country": "US",
          "postal_code": "14236",
          "region": "NY",
          "street": "2992 Cameron Road",
        }
        "ytd_interest_paid": 12300.4,
        "ytd_principal_paid": 12340.5
      }
    ],
    "student": [
      {
        "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
        "account_number": "4277075694",
        "disbursement_dates": ["2002-08-28"],
        "expected_payoff_date": "2032-07-28",
        "guarantor": "DEPT OF ED",
        "interest_rate_percentage": 5.25,
        "is_overdue": false,
        "last_payment_amount": 138.05,
        "last_payment_date": "2019-04-22",
        "last_statement_issue_date": "2019-04-28",
        "loan_name": "Consolidation",
        "loan_status": {
          "end_date": "2032-07-28",
          "type": "repayment"
        },
        "minimum_payment_amount": 25,
        "next_payment_due_date": "2019-05-28",
        "origination_date": "2002-08-28",
        "origination_principal_amount": 25000,
        "outstanding_interest_amount": 6227.36,
        "payment_reference_number": "4277075694",
        "pslf_status": {
          "estimated_eligibility_date": "2021-01-01",
          "payments_made": 200,
          "payments_remaining": 160
        },
        "repayment_plan": {
          "description": "Standard Repayment",
          "type": "standard"
        },
        "sequence_number": "1",
        "servicer_address": {
          "city": "San Matias",
          "country": "US",
          "postal_code": "99415",
          "region": "CA",
          "street": "123 Relaxation Road"
        },
        "ytd_interest_paid": 280.55,
        "ytd_principal_paid": 271.65
      }
    ]
  },
  "request_id": "dTnnm60WgKGLnKL"
}
```

#### Set up webhook listener 

To be alerted to changes in Liabilities data, listen for the [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/liabilities/index.html.md#default_update) webhook. Upon receiving this webhook, you can call [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) again to retrieve updated liabilities information.

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Liabilities - Introduction to Liabilities | Plaid Docs

Introduction to Liabilities  
=============================

#### Access data for private student loans, mortgages, and credit cards using the Liabilities product. 

Get started with Liabilities

[API Reference](https://plaid.com/docs/api/products/liabilities/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md)

#### Overview 

Plaid's Liabilities product allows you to access information about a user's debts. A common application is personal financial management tools to help customers manage or refinance debt. Liabilities is supported in the US and Canada (Canada coverage is limited).

#### Liabilities data 

With Liabilities, you can view account information for credit cards, PayPal credit accounts, private student loans, and mortgages in the US. Available information includes balance, next payment date and amount, loan terms such as duration and interest rate, and originator information such as the origination date and initial loan amount. Liabilities data is refreshed approximately once per day, and the latest data can be accessed by calling [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) .

Note that liabilities data does not contain detailed transaction history for credit card accounts. For credit card account transactions, use the [Transactions](https://plaid.com/docs/transactions/index.html.md) product.

```json
"credit": [
  {
    "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
    "aprs": [
      {
        "apr_percentage": 15.24,
        "apr_type": "balance_transfer_apr",
        "balance_subject_to_apr": 1562.32,
        "interest_charge_amount": 130.22
      },
      {
        "apr_percentage": 27.95,
        "apr_type": "cash_apr",
        "balance_subject_to_apr": 56.22,
        "interest_charge_amount": 14.81
      },
      {
        "apr_percentage": 12.5,
        "apr_type": "purchase_apr",
        "balance_subject_to_apr": 157.01,
        "interest_charge_amount": 25.66
      },
      {
        "apr_percentage": 0,
        "apr_type": "special",
        "balance_subject_to_apr": 1000,
        "interest_charge_amount": 0
      }
    ],
    "is_overdue": false,
    "last_payment_amount": 168.25,
    "last_payment_date": "2019-05-22",
    "last_statement_issue_date": "2019-05-28",
    "last_statement_balance": 1708.77,
    "minimum_payment_amount": 20,
    "next_payment_due_date": "2020-05-28"
  }
]
```

```json
"student": [
  {
    "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
    "account_number": "4277075694",
    "disbursement_dates": [
      "2002-08-28"
    ],
    "expected_payoff_date": "2032-07-28",
    "guarantor": "DEPT OF ED",
    "interest_rate_percentage": 5.25,
    "is_overdue": false,
    "last_payment_amount": 138.05,
    "last_payment_date": "2019-04-22",
    "last_statement_issue_date": "2019-04-28",
    "loan_name": "Consolidation",
    "loan_status": {
      "end_date": "2032-07-28",
      "type": "repayment"
    },
    "minimum_payment_amount": 25,
    "next_payment_due_date": "2019-05-28",
    "origination_date": "2002-08-28",
    "origination_principal_amount": 25000,
    "outstanding_interest_amount": 6227.36,
    "payment_reference_number": "4277075694",
    "pslf_status": {
      "estimated_eligibility_date": "2021-01-01",
      "payments_made": 200,
      "payments_remaining": 160
    },
    "repayment_plan": {
      "description": "Standard Repayment",
      "type": "standard"
    },
    "sequence_number": "1",
    "servicer_address": {
      "city": "San Matias",
      "country": "US",
      "postal_code": "99415",
      "region": "CA",
      "street": "123 Relaxation Road"
    },
    "ytd_interest_paid": 280.55,
    "ytd_principal_paid": 271.65
  }
]
```

```json
"mortgage": [
  {
    "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
    "account_number": "3120194154",
    "current_late_fee": 25.0,
    "escrow_balance": 3141.54,
    "has_pmi": true,
    "has_prepayment_penalty": true,
    "interest_rate": {
      "percentage": 3.99,
      "type": "fixed",
    },
    "last_payment_amount": 3141.54,
    "last_payment_date": "2019-08-01",
    "loan_term": "30 year",
    "loan_type_description": "conventional",
    "maturity_date": "2045-07-31",
    "next_monthly_payment": 3141.54,
    "next_payment_due_date": "2019-11-15",
    "origination_date": "2015-08-01",
    "origination_principal_amount": 425000,
    "past_due_amount": 2304,
    "property_address": {
      "city": "Malakoff",
      "country": "US",
      "postal_code": "14236",
      "region": "NY",
      "street": "2992 Cameron Road",
    }
    "ytd_interest_paid": 12300.4,
    "ytd_principal_paid": 12340.5
  }
]
```

#### Payment history 

The information returned by a [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) request contains recent payment information, such as the date and amount of the most recent payment. To view further payment history, you can use Plaid's [Transactions](https://plaid.com/docs/transactions/index.html.md) product.

#### Liabilities webhooks 

Plaid checks for updated Liabilities data approximately once per day and uses webhooks to inform you of any changes so you can keep your app up to date. For more detail on how to listen and respond to these webhooks, see [Liabilities webhooks](https://plaid.com/docs/api/products/liabilities/index.html.md#webhooks) .

#### Testing Liabilities 

Liabilities can be tested in Sandbox without any additional permissions.

Plaid also provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) with test data for testing student loan accounts in Sandbox. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) .

#### Liabilities pricing 

Liabilities is billed on a [subscription model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

To get started building with Liabilities, see [Add Liabilities to your App](https://plaid.com/docs/liabilities/add-to-app/index.html.md) .

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Link - Android | Plaid Docs

Link Android SDK 
=================

#### Learn how to integrate your app with the Link Android SDK 

#### Overview 

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid in your Android app. Link is a drop-in module that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.), without passing sensitive personal information to your server.

To get started with Plaid Link for Android, clone the [GitHub repository](https://github.com/plaid/plaid-link-android) and try out the example application, which provides a reference implementation in both Java and Kotlin. Youʼll want to sign up for [free API keys](https://dashboard.plaid.com/developers/keys) through the Plaid Dashboard to get started.

(An image of "Five screenshots of Plaid Link for Android: connect service, select institution, enter credentials, select accounts, and success confirmation.")

Prefer to learn by watching? A [video guide](https://youtu.be/oM7vL49I5tc) is available for this content.

#### Initial Android setup 

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

##### Register your app ID 

To register your Android app ID:

1.  Sign in to the [Plaid Dashboard](https://dashboard.plaid.com/signin) and go to the [Developers -> API](https://dashboard.plaid.com/developers/api) page.
2.  Next to **Allowed Android Package Names** click **Configure** then **Add New Android Package Name**.
3.  Enter your package name, for example `com.plaid.example`.
4.  Click **Save Changes**.

Your Android app is now set up and ready to start integrating with the Plaid SDK.

New versions of the Android SDK are released frequently, at least once every few months. Major releases occur annually. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

##### Update your project plugins 

In your root-level (project-level) Gradle file (`build.gradle`), add rules to include the Android Gradle plugin. Check that you have Google's Maven repository as well.

```undefined
buildscript {
    repositories {
        // Check that you have the following line (if not, add it):
        google()  // Google's Maven repository
        mavenCentral() // Include to import Plaid Link Android SDK
    }
    dependencies {
        // ...
    }
}
```

##### Add the PlaidLink SDK to your app 

In your module (app-level) Gradle file (usually `app/build.gradle`), add a line to the bottom of the file. The latest version of the PlaidLink SDK is (An image of "Maven Central") and can be found on [Maven Central](https://search.maven.org/artifact/com.plaid.link/sdk-core) .

```typescript
android {
  defaultConfig {
    minSdkVersion 21 // or greater
  }
}


dependencies {
  // ...
  implementation 'com.plaid.link:sdk-core:'
}
```

##### Enable camera support (Identity Verification only) 

If your app uses [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , a user may need to take a picture of identity documentation or a selfie during the Link flow. To support this workflow, the [CAMERA](https://developer.android.com/reference/android/Manifest.permission#CAMERA) , [WRITE\_EXTERNAL\_STORAGE](https://developer.android.com/reference/android/Manifest.permission#WRITE_EXTERNAL_STORAGE) , [RECORD\_AUDIO](https://developer.android.com/reference/android/Manifest.permission#RECORD_AUDIO) , and [MODIFY\_AUDIO\_SETTINGS](https://developer.android.com/reference/android/Manifest.permission#MODIFY_AUDIO_SETTINGS) permissions need to be added to your application's `AndroidManifest.xml`. (While Plaid does not record any audio, some older Android devices require these last two permissions to use the camera.) The `WRITE_EXTERNAL_STORAGE` permission should be limited to < Android 9 (i.e. maxSdk=28). If these permissions are not granted in an app that uses Identity Verification, the app may crash during Link.

#### Opening Link 

Before you can open Link, you need to first create a `link_token` by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) from your backend. This call should **never** happen directly from the mobile client, as it risks exposing your API secret. The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call must include the `android_package_name` parameter, which should match the `applicationId` from your app-level `build.gradle` file. You can learn more about `applicationId` in Google's [Android developer documentation](https://developer.android.com/studio/build/application-id) .

```javascript
const request: LinkTokenCreateRequest = {
  user: {
    client_user_id: 'user-id',
  },
  client_name: 'Plaid Test App',
  products: ['auth', 'transactions'],
  country_codes: ['GB'],
  language: 'en',
  webhook: 'https://sample-web-hook.com',
  android_package_name: 'com.plaid.example'
  },
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Create a LinkTokenConfiguration 

Each time you open Link, you will need to get a new `link_token` from your server and create a new `LinkTokenConfiguration` object with it.

```typescript
val linkTokenConfiguration = linkTokenConfiguration {
  token = "LINK_TOKEN_FROM_SERVER"
}
```

The Link SDK runs as a separate `Activity` within your app. In order to return the result to your app, it supports both the standard `startActivityForResult` and `onActivityResult` and the `ActivityResultContract` [result APIs](https://developer.android.com/training/basics/intents/result) .

Select group for content switcher

Activity Result APIsStandard Activity APIs

##### Register a callback for an Activity Result 

```typescript
private val linkAccountToPlaid =
registerForActivityResult(FastOpenPlaidLink()) {
  when (it) {
    is LinkSuccess -> /* handle LinkSuccess */
    is LinkExit -> /* handle LinkExit */
  }
}
```

##### Create a PlaidHandler 

Create a `PlaidHandler` - A `PlaidHandler` is a one-time use object used to open a Link session. It should be created as early as possible to warm up Link so that it opens quickly. We recommend doing this as early as possible, since it must be completed before Link opens, and if you create it just before opening Link, it can have a perceptible impact on Link startup time.

```typescript
val plaidHandler: PlaidHandler = 
  Plaid.create(application, linkTokenConfiguration)
```

##### Open Link 

```typescript
linkAccountToPlaid.launch(plaidHandler)
```

At this point, Link will open, and will trigger the `onSuccess` callback if the user successfully completes the Link flow.

\=\*=\*=\*=

#### onSuccess 

The method is called when a user successfully links an Item. The onSuccess handler returns a `LinkConnection` class that includes the `public_token`, and additional Link metadata in the form of a `LinkConnectionMetadata` class.

**Properties**

[publicToken](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-publicToken)

String

Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used.

[metadata](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata)

Object

Displayed once a user has successfully completed Link.

[accounts](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts)

List<LinkAccount>

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](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts-id)

string

The Plaid `account_id`

[name](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts-name)

string

The official account name

[mask](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts-mask)

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

[subtype](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts-subtype)

LinkAccountSubtype

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[type](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts-subtype-type)

LinkAccountType

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[verification\_status](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-accounts-verification-status)

nullable, string

Indicates an Item's micro-deposit-based verification or database verification status. 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 deposit.  
`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.  
`database_matched`: The Item has successfully been verified using Plaid's data sources.  
`database_insights_pending`: The Database Insights result is pending and will be available upon Auth request.  
`null`: Neither micro-deposit-based verification nor database verification are being used for the Item.

[institution](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-institution)

nullable, object

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-institution-name)

string

The full institution name, such as `'Wells Fargo'`

[institution\_id](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-institution-institution-id)

string

The Plaid institution identifier

[linkSessionId](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-linkSessionId)

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

[metadataJson](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-metadataJson)

nullable, Map

The data directly returned from the server with no client side changes.

```typescript
val success = result as LinkSuccess


// Send public_token to your server, exchange for access_token 
// (if using Item-based products)
val publicToken = success.publicToken
val metadata = success.metadata
metadata.accounts.forEach { account ->
  val accountId = account.id
  val accountName = account.name
  val accountMask = account.mask
  val accountSubType = account.subtype
}
val institutionId = metadata.institution?.id
val institutionName = metadata.institution?.name
```

\=\*=\*=\*=

#### onExit 

The `onExit` handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The `PlaidError` returned from the `onExit` handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant information in Plaid Support requests for the user.

**Properties**

[error](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error)

Map<String, Object>

An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, `error` will be `null`.

[displayMessage](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error-displayMessage)

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

[errorCode](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error-errorCode)

String

The particular error code. Each `errorType` has a specific set of `errorCodes`. A code of 499 indicates a client-side exception.

[json](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error-errorCode-json)

String

A string representation of the error code.

[errorType](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error-errorCode-errorType)

String

A broad categorization of the error.

[errorMessage](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error-errorMessage)

String

A developer-friendly representation of the error code.

[errorJson](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-error-errorJson)

nullable, String

The data directly returned from the server with no client side changes.

[LinkExitMetadata](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata)

Map<String, Object>

An object containing information about the exit event

[linkSessionId](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-linkSessionId)

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

[institution](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-institution)

nullable, object

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-institution-name)

string

The full institution name, such as `'Wells Fargo'`

[institution\_id](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-institution-institution-id)

string

The Plaid institution identifier

[status](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status)

nullable, String

The point at which the user exited the Link flow. One of the following values.

[requires\_questions](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-requires-questions)

User prompted to answer security questions

[requires\_selections](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-requires-selections)

User prompted to answer multiple choice question(s)

[requires\_recaptcha](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-requires-recaptcha)

User prompted to solve a reCAPTCHA challenge

[requires\_code](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-requires-code)

User prompted to provide a one-time passcode

[choose\_device](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-choose-device)

User prompted to select a device on which to receive a one-time passcode

[requires\_credentials](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-requires-credentials)

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

[requires\_account\_selection](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-requires-account-selection)

User prompted to select one or more financial accounts to share

[institution\_not\_found](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-institution-not-found)

User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.

[institution\_not\_supported](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-institution-not-supported)

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

[unknown](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-status-unknown)

An exit status that is not handled by the current version of the SDK

[requestId](https://plaid.com/docs/link/android/index.html.md#link-android-onexit-LinkExitMetadata-requestId)

nullable, String

The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation

```typescript
val exit = result as LinkExit


val error = exit.error
error?.let { err ->
  val errorCode = err.errorCode
  val errorMessage = err.errorMessage
  val displayMessage = err.displayMessage
}
val metadata = exit.metadata
val institutionId = metadata.institution?.id
val institutionName = metadata.institution?.name
val linkSessionId = metadata.linkSessionId;
val requestId = metadata.requestId;
```

\=\*=\*=\*=

#### onEvent 

The `onEvent` callback is called at certain points in the Link flow. Unlike the handlers for `onSuccess` and `onExit`, the `onEvent` handler is initialized as a global lambda passed to the `Plaid` class. `OPEN`, `LAYER_READY`, and `LAYER_NOT_AVAILABLE` events will be sent in real-time, and remaining events will be sent when the Link session is finished and `onSuccess` or `onExit` is called. Callback ordering is not guaranteed; `onEvent` callbacks may fire before, after, or surrounding the `onSuccess` or `onExit` callback, and event callbacks are not guaranteed to fire in the order in which they occurred. If you need the exact time when an event happened, use the `timestamp` property.  
The following `onEvent` callbacks are stable, which means that they are suitable for programmatic use in your application's logic: `OPEN`, `EXIT`, `HANDOFF`, `SELECT_INSTITUTION`, `ERROR`, `BANK_INCOME_INSIGHTS_COMPLETED`, `IDENTITY_VERIFICATION_PASS_SESSION`, `IDENTITY_VERIFICATION_FAIL_SESSION`, `LAYER_READY`, `LAYER_NOT_AVAILABLE`. The remaining callback events are informational and subject to change, and should be used for analytics and troubleshooting purposes only.

**Properties**

[eventName](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName)

String

A string representing the event that has just occurred in the Link flow.

[AUTO\_SUBMIT\_PHONE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-AUTO-SUBMIT-PHONE)

The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid.

[BANK\_INCOME\_INSIGHTS\_COMPLETED](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-BANK-INCOME-INSIGHTS-COMPLETED)

The user has completed the Assets and Bank Income Insights flow.

[CLOSE\_OAUTH](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-CLOSE-OAUTH)

The user closed the third-party website or mobile app without completing the OAuth flow.

[CONNECT\_NEW\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-CONNECT-NEW-INSTITUTION)

The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Remember Me flow.

[ERROR](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-ERROR)

A recoverable error occurred in the Link flow, see the `error_code` metadata.

[EXIT](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-EXIT)

The user has exited without completing the Link flow and the [onExit](https://plaid.com#onexit) callback is fired.

[FAIL\_OAUTH](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-FAIL-OAUTH)

The user encountered an error while completing the third-party's OAuth login flow.

[HANDOFF](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-HANDOFF)

The user has exited Link after successfully linking an Item.

[IDENTITY\_MATCH\_FAILED](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-MATCH-FAILED)

An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match.

[IDENTITY\_MATCH\_PASSED](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-MATCH-PASSED)

An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match.

[IDENTITY\_VERIFICATION\_START\_STEP](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-START-STEP)

The user has started a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_PASS\_STEP](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-PASS-STEP)

The user has passed a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_FAIL\_STEP](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-FAIL-STEP)

The user has failed a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_PENDING\_REVIEW\_STEP](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-PENDING-REVIEW-STEP)

The user has reached the pending review state.

[IDENTITY\_VERIFICATION\_CREATE\_SESSION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-CREATE-SESSION)

The user has started a new Identity Verification session.

[IDENTITY\_VERIFICATION\_RESUME\_SESSION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-RESUME-SESSION)

The user has resumed an existing Identity Verification session.

[IDENTITY\_VERIFICATION\_PASS\_SESSION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-PASS-SESSION)

The user has passed their Identity Verification session.

[IDENTITY\_VERIFICATION\_FAIL\_SESSION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-FAIL-SESSION)

The user has failed their Identity Verification session.

[IDENTITY\_VERIFICATION\_PENDING\_REVIEW\_SESSION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-PENDING-REVIEW-SESSION)

The user has completed their Identity Verification session, which is now in a pending review state.

[IDENTITY\_VERIFICATION\_OPEN\_UI](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-OPEN-UI)

The user has opened the UI of their Identity Verification session.

[IDENTITY\_VERIFICATION\_RESUME\_UI](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-RESUME-UI)

The user has resumed the UI of their Identity Verification session.

[IDENTITY\_VERIFICATION\_CLOSE\_UI](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-IDENTITY-VERIFICATION-CLOSE-UI)

The user has closed the UI of their Identity Verification session.

[LAYER\_AUTOFILL\_NOT\_AVAILABLE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-LAYER-AUTOFILL-NOT-AVAILABLE)

The user's date of birth passed to Link is not eligible for Layer autofill.

[LAYER\_NOT\_AVAILABLE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-LAYER-NOT-AVAILABLE)

The user phone number passed to Link is not eligible for Layer.

[LAYER\_READY](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-LAYER-READY)

The user phone number passed to Link is eligible for Layer and `open()` may now be called.

[MATCHED\_SELECT\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-MATCHED-SELECT-INSTITUTION)

The user selected an institution that was presented as a matched institution. This event can be emitted either during the legacy version of the Returning User Experience flow or if the institution's `routing_number` was provided when calling `/link/token/create`. To distinguish between the two scenarios, see `LinkEventMetadata.match_reason`.

[OPEN](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-OPEN)

The user has opened Link.

[OPEN\_MY\_PLAID](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-OPEN-MY-PLAID)

The user has opened my.plaid.com. This event is only emitted when Link is initialized with Assets as a product.

[OPEN\_OAUTH](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-OPEN-OAUTH)

The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.

[SEARCH\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SEARCH-INSTITUTION)

The user has searched for an institution.

[SKIP\_SUBMIT\_PHONE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SKIP-SUBMIT-PHONE)

The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Remember Me flow.

[SELECT\_BRAND](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SELECT-BRAND)

The user selected a brand, e.g. Bank of America. The `SELECT_BRAND` event is only emitted for large financial institutions with multiple online banking portals.

[SELECT\_DEGRADED\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SELECT-DEGRADED-INSTITUTION)

The user selected an institution with a `DEGRADED` health status and was shown a corresponding message.

[SELECT\_DOWN\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SELECT-DOWN-INSTITUTION)

The user selected an institution with a `DOWN` health status and was shown a corresponding message.

[SELECT\_FILTERED\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SELECT-FILTERED-INSTITUTION)

The user selected an institution Plaid does not support all requested products for and was shown a corresponding message.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SELECT-INSTITUTION)

The user selected an institution.

[SUBMIT\_ACCOUNT\_NUMBER](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SUBMIT-ACCOUNT-NUMBER)

The user has submitted an account number. This event emits the `account_number_mask` metadata to indicate the mask of the account number the user provided.

[SUBMIT\_CREDENTIALS](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SUBMIT-CREDENTIALS)

The user has submitted credentials.

[SUBMIT\_MFA](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SUBMIT-MFA)

The user has submitted MFA.

[SUBMIT\_OTP](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SUBMIT-OTP)

The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_PHONE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SUBMIT-PHONE)

The user has submitted their phone number. This event is only emitted in the Link Remember Me flow.

[SUBMIT\_ROUTING\_NUMBER](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-SUBMIT-ROUTING-NUMBER)

The user has submitted a routing number. This event emits the `routing_number` metadata to indicate user's routing number.

[TRANSITION\_VIEW](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-TRANSITION-VIEW)

The `TRANSITION_VIEW` event indicates that the user has moved from one view to the next.

[UPLOAD\_DOCUMENTS](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-UPLOAD-DOCUMENTS)

The user is asked to upload documents (for Income verification).

[VERIFY\_PHONE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-VERIFY-PHONE)

The user has successfully verified their phone number using OTP. This event is only emitted in the Link Remember Me flow.

[VIEW\_DATA\_TYPES](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-VIEW-DATA-TYPES)

The user has viewed data types on the data transparency consent pane.

[UNKNOWN](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-eventName-UNKNOWN)

The `UNKNOWN` event indicates that the event is not handled by the current version of the SDK.

[LinkEventMetadata](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata)

Map<String, Object>

An object containing information about the event.

[accountNumberMask](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-accountNumberMask)

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

[errorCode](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-errorCode)

String

The error code that the user encountered. Emitted by: `ERROR`, `EXIT`.

[errorMessage](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-errorMessage)

String

The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.

[errorType](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-errorType)

String

The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.

[exitStatus](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-exitStatus)

String

The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`.

[institutionId](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-institutionId)

String

The ID of the selected institution. Emitted by: _all events_.

[institutionName](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-institutionName)

String

The name of the selected institution. Emitted by: _all events_.

[institutionSearchQuery](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-institutionSearchQuery)

String

The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.

[isUpdateMode](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-isUpdateMode)

String

Indicates if the current Link session is an update mode session. Emitted by: `OPEN`.

[matchReason](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-matchReason)

nullable, 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`.

[routingNumber](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-routingNumber)

Optional<String>

The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`.

[linkSessionId](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-linkSessionId)

String

The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_.

[mfaType](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-mfaType)

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

[requestId](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-requestId)

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

[selection](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-selection)

String

The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`.

[timestamp](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-timestamp)

String

An ISO 8601 representation of when the event occurred. For example `2017-09-14T14:42:19.350Z`. Emitted by: _all events_.

[viewName](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName)

String

The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`.

[ACCEPT\_TOS](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-ACCEPT-TOS)

The view showing Terms of Service in the identity verification flow.

[CONNECTED](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-CONNECTED)

The user has connected their account.

[CONSENT](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-CONSENT)

We ask the user to consent to the privacy policy.

[CREDENTIAL](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-CREDENTIAL)

Asking the user for their account credentials.

[DOCUMENTARY\_VERIFICATION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-DOCUMENTARY-VERIFICATION)

The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).

[ERROR](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-ERROR)

An error has occurred.

[EXIT](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-EXIT)

Confirming if the user wishes to close Link.

[INSTANT\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-INSTANT-MICRODEPOSIT-AUTHORIZED)

The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.

[KYC\_CHECK](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-KYC-CHECK)

The view representing the "know your customer" step in the identity verification flow.

[LOADING](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-LOADING)

Link is making a request to our servers.

[MFA](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-MFA)

The user is asked by the institution for additional MFA authentication.

[NUMBERS](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-NUMBERS)

The user is asked to insert their account and routing numbers.

[NUMBERS\_SELECT\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-NUMBERS-SELECT-INSTITUTION)

The user goes through the Same Day micro-deposits flow with Reroute to Credentials.

[OAUTH](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-OAUTH)

The user is informed they will authenticate with the financial institution via OAuth.

[PROFILE\_DATA\_REVIEW](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-PROFILE-DATA-REVIEW)

The user is asked to review their profile data in the Layer flow.

[RECAPTCHA](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-RECAPTCHA)

The user was presented with a Google reCAPTCHA to verify they are human.

[RISK\_CHECK](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-RISK-CHECK)

The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).

[SAME\_DAY\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SAME-DAY-MICRODEPOSIT-AUTHORIZED)

The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.

[SCREENING](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SCREENING)

The watchlist screening step in the identity verification flow.

[SELECT\_ACCOUNT](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELECT-ACCOUNT)

We ask the user to choose an account.

[SELECT\_AUTH\_TYPE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELECT-AUTH-TYPE)

The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).

[SELECT\_BRAND](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELECT-BRAND)

The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELECT-INSTITUTION)

We ask the user to choose their institution.

[SELECT\_SAVED\_ACCOUNT](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELECT-SAVED-ACCOUNT)

The user is asked to select their saved accounts and/or new accounts for linking in the Link Remember Me flow.

[SELECT\_SAVED\_INSTITUTION](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELECT-SAVED-INSTITUTION)

The user is asked to pick a saved institution or link a new one in the Link Remember Me flow.

[SELFIE\_CHECK](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SELFIE-CHECK)

The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.

[SUBMIT\_PHONE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-SUBMIT-PHONE)

The user is asked for their phone number in the Link Remember Me flow.

[UPLOAD\_DOCUMENTS](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-UPLOAD-DOCUMENTS)

The user is asked to upload documents (for Income verification).

[VERIFY\_PHONE](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-VERIFY-PHONE)

The user is asked to verify their phone OTP in the Link Remember Me flow.

[VERIFY\_SMS](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-viewName-VERIFY-SMS)

The SMS verification step in the identity verification flow.

[metadataJson](https://plaid.com/docs/link/android/index.html.md#link-android-onevent-LinkEventMetadata-metadataJson)

nullable, String

The data directly returned from the server with no client side changes.

```typescript
Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }
```

\=\*=\*=\*=

#### Submit 

The `submit` function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number).

**Properties**

[submissionData](https://plaid.com/docs/link/android/index.html.md#link-android-submit-submissionData)

object

Data to submit during a Link session.

[phoneNumber](https://plaid.com/docs/link/android/index.html.md#link-android-submit-submissionData-phoneNumber)

String

The end user phone number.

[dateOfBirth](https://plaid.com/docs/link/android/index.html.md#link-android-submit-submissionData-dateOfBirth)

String

The end user date of birth. To be provided in the format "yyyy-mm-dd".

```typescript
val submissionData = SubmissionData(phoneNumber)
plaidHandler.submit(submissionData)
```

\=\*=\*=\*=

#### Upgrading 

The latest version of the SDK is available from [GitHub](https://github.com/plaid/plaid-link-android) . New versions of the SDK are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application.

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

\=\*=\*=\*=

#### Next steps 

If you run into problems integrating with Plaid Link on Android, see [Troubleshooting the Plaid Link Android SDK](https://plaid.com/docs/link/android/troubleshooting/index.html.md) .

Once you've gotten Link working, see [Link best practices](https://plaid.com/docs/link/best-practices/index.html.md) for recommendations on further improving the Link flow.

---


# Link - Troubleshooting | Plaid Docs

Troubleshooting the Plaid Link Android SDK 
===========================================

\=\*=\*=\*=

#### Enabling Logs 

The Link SDK logs information to LogCat at several points in the flow. Pass a `LinkLogLevel` value with the `LinkTokenConfiguration` to see the logs. The levels from least to most verbose: `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`.

```typescript
val linkTokenConfiguration = linkTokenConfiguration {
  token = "LINK_TOKEN_FROM_SERVER"
  logLevel = if (BuildConfig.DEBUG) LinkLogLevel.VERBOSE else LinkLogLevel.ERROR
}
```

\=\*=\*=\*=

#### Troubleshooting OAuth errors 

A troubleshooting guide for common OAuth errors is below.

\=\*=\*=\*=

#### No redirect out of app 

##### Link user experience 

*   In Link, after clicking "Continue" on the OAuth screen, nothing happens.

##### Common causes 

*   The user may be using an unsupported browser that is not compatible with Plaid's OAuth redirects, such as DuckDuckGo. For more details on which browsers are supported, see [Supported browsers](https://plaid.com/docs/link/web/index.html.md#supported-browsers) .

##### Troubleshooting steps 

\=\*=\*=\*=

#### No redirect back to app 

##### Link user experience 

*   After completing OAuth in the browser or financial institution's app, the user is not redirected back to your app.

##### Common causes 

*   The webpage is unable to locate an app on the device with a package id matching the one used to create the Link token.

##### Troubleshooting steps 

\=\*=\*=\*=

#### The Play Store opened upon redirect 

##### Link user experience 

*   After completing OAuth in the browser or financial institution's app, the Google Play store opened.

##### Common causes 

*   The webpage is unable to locate an app on the device with the package id matching the one used to create the Link token.

##### Troubleshooting steps 

\=\*=\*=\*=

#### Link opens, then immediately closes upon redirect 

##### Link user experience 

After completing OAuth in the browser or financial institution's app, Link opens and then closes again.

##### Common causes 

*   The webpage redirected back to the wrong application on the device causing Link to open and immediately close again as it gets data from a different session.
*   You may have both a test and a release version of your app installed on your device and used the wrong package name when creating the Link token.

##### Troubleshooting steps 

\=\*=\*=\*=

#### Other common errors 

To troubleshoot an error with an error code, use the [error troubleshooting guide](https://plaid.com/docs/errors/index.html.md) .

---


# Link - Optimizing Link conversion | Plaid Docs

Optimizing Link conversion 
===========================

#### Discover best practices for improving Link conversion 

#### Overview 

This guide contains tips for optimizing your existing Link implementation to help increase conversion and improve your users’ experiences with Link. If you are new to Link or don’t yet have a working Link integration, see [Link overview](https://plaid.com/docs/link/index.html.md) for instructions on getting started with Link.

If you are using pay-by-bank flows, also see [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for tips on getting users to use the Link-based payments flow rather than paying via card.

#### Measuring Link conversion 

Before making changes to your integration to improve conversion, you should first understand your current conversion rates. To learn how, see [Tracking Link conversion](https://plaid.com/docs/link/measuring-conversion/index.html.md) .

#### Improving Link conversion 

Many different steps can be taken to maximize Link conversion, and the exact impact of these steps will vary for each customer and use case. The recommendations below are provided in general priority order.

##### Initialize with a minimal set of products 

In general, calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with a minimal set of products will both increase conversion and reduce your costs. For more details, see [Choosing how to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) .

##### Implement full OAuth support on mobile, including app-to-app 

While supporting mobile app-to-app impacts only a small number of banks (currently only Chase), the impact on conversion for eligible users is very large, as app-to-app flows can allow users to authenticate with biometrics instead of a username and password. For iOS, supporting app-to-app requires [creating an apple-app-site-association file](https://plaid.com/docs/link/oauth/index.html.md#ios-sdk-react-native-ios) to support universal links. On Android, supporting app-to-app requires [registering your Android package name](https://plaid.com/docs/link/oauth/index.html.md#android-sdk-react-native-android) . For more details, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) .

##### Pre-initialize Link for lower UI latency 

All Plaid SDKs offer a method to pre-initialize Link before opening it -- for example, by calling the `create()` method on web, React Native, or iOS, or creating a `PlaidHandler` on Android. It is recommended to call this method as soon as you load the view or screen from which the end user can open Link. Pre-initializing Link as soon as possible, before the `open()` method is called, results in lower latency for your end-user in loading the Link UI, leading to increased conversion.

Support for pre-initialization was added in March 2024. You must be using an up-to-date version of Plaid Link SDKs to benefit from the performance enhancements of this approach.

##### Provide pre-Link messaging 

Link conversion is highest when users have the right expectations set going into Link. Your app should explain why you use Plaid, the benefits for the user of connecting their account, and that the user's information will be secure. It should also set the user's expectations around what information they will need to provide during the Link flow. Plaid should be configured as the default experience. For more details, including visual examples, see [Pre-Link messaging for optimizing conversion](https://plaid.com/docs/link/messaging/index.html.md) .

##### Update the Link SDK regularly 

Plaid makes continual updates to Plaid Link to improve conversion. If you are using Link on web, you will automatically be on the latest version; if you are using one of Plaid's SDKs for [iOS](https://github.com/plaid/plaid-link-ios) , [Android](https://github.com/plaid/plaid-link-android) , or [React Native](https://github.com/plaid/react-native-plaid-link-sdk) , we recommend you update regularly (ideally once at month, and at least once per quarter) to ensure you have access to the latest Link conversion improvements.

##### (For Auth customers) Implement micro-deposit based Auth 

While the vast majority of users can use Plaid's default Auth flows, some users, especially those at smaller banks and credit unions, have accounts that do not support those flows. Implementing micro-deposit-based Auth flows will increase conversion by allowing these users to link their accounts. For more details, see [Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) .

##### (For pay by bank use cases) Implement Embedded Institution Search 

If you are building pay by bank flows, implementing the [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) UI for Link can increase the percentage of customers who choose to pay by bank rather than via a different means of payment.

##### Use Link Recovery 

[Link Recovery (beta)](https://plaid.com/docs/link/link-recovery/index.html.md) allows you to recapture end users who abandoned Link due to temporary institution outages and notify them when the issue is resolved. To learn more and request access to the beta, see [Link Recovery](https://plaid.com/docs/link/link-recovery/index.html.md) .

##### Configure Link for your user's country and language 

For apps with multi-language experiences, [custom profiles](https://plaid.com/docs/link/customization/index.html.md) improve conversion by allowing you to display Link in your user's preferred language. Calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the `country` parameter set to your user's specific country, rather than all countries your app supports, will allow Link to show a more accurately targeted list of institutions. For Auth customers, calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `country` set to just `US` is also required to enable the conversion-maximizing Instant Match and micro-deposit based [Auth flows](https://plaid.com/docs/auth/coverage/index.html.md) .

##### Customize Link with your organization's branding 

Plaid allows you to customize certain aspects of the Link UI. Customizing these in a way that matches your app -- for example, [uploading your organization's logo](https://plaid.com/docs/link/customization/index.html.md#consent-pane-customizations) to be used on the Link consent pane or [matching your brand colors](https://plaid.com/docs/link/customization/index.html.md#color-scheme) can increase conversion. For more details, see [Customizing Link](https://plaid.com/docs/link/index.html.md) .

##### (If applicable) Use the Institution Select shortcut 

If you already know the institution your user plans to connect before the Link flow is launched, you can highlight this institution in the Institution Select UI by specifying the [routing number](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-institution-data-routing-number) during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. For more details, see [Institution Select shortcut](https://plaid.com/docs/link/customization/index.html.md#institution-select-shortcut) .

---


# Link - Customizing Link | Plaid Docs

Link customization 
===================

#### Learn how to customize the Link UI for your app 

#### Link customization overview 

You have the ability to customize multiple parts of the Link UI from the [Plaid Dashboard](https://dashboard.plaid.com/link) .

(An image of "Plaid dashboard showing Link customization options with institution selection, search bar, and list of bank logos.")

You can create multiple Link customizations in order to show different versions of Link to different users. For example, you can show an English-configured customization to users who have set their language to English, and a French-configured customization to users who have set their language to French.

To create a customization, access the **Link** menu within the [Plaid Dashboard](https://dashboard.plaid.com/link) and select **Link Customization**. You can then create a new customization by clicking on the drop-down menu in the upper right and selecting **Create new customization**. Or, to create a customization based on an existing customization, open the settings pane, accessible via the gear icon in the upper-right corner of the Link customization page, and use the **Duplicate** button. From the settings pane, you can also modify the countries and languages the customization applies to, as well as change its name.

(An image of "Edit French settings pane showing options for countries, language, and customization name, with Duplicate, Save, and Delete buttons.")

To use a customization, set the `link_customization_name` parameter to the customization name when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

In order for a customization to be applied, the language and country settings in Link must _exactly_ match those specified in the customization. For example, a customization with the country set to **United States** and **Canada** will not be applied if the `country_codes` setting provided to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is `['US']`; it must be `['US', 'CA']`.

#### Account Select 

The Account Select pane is a required pane where users indicate which accounts they want to share data for.

(An image of "Three Account Select panes in Plaid Link: one account selected, multiple accounts selected, and all accounts selected.")

Enabled for one account, Enabled for multiple accounts, and Enabled for all accounts Account Select panes, respectively

This pane can be configured to allow for single account selection, multi account selection, or all accounts preselected. Your use case may influence the setting you want to choose:

*   If your Plaid use case is banking, consumer payments, or wealth, we recommend that you use the "Enabled for one account" or the "Enabled for multiple accounts" view behavior.
*   If your Plaid use case is personal financial management or lending, you may prefer to use the "Enabled for all accounts" view behavior. When a user connects their account via a financial institution’s OAuth flow, the Account Select pane may be skipped if Plaid determines that the flow has already fulfilled the account selection step (e.g. if Link is customized to enable multiple accounts to be selected and the financial institution’s OAuth flow supports this step, Plaid’s Account Select pane will not be shown).

Note that if you have enabled multi account selection or all accounts selected, this behavior may be overridden in Link during Link flows that do not support the usage of multiple accounts. For example, the [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) and [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) Auth flows require the user to enter the account and routing number for a specific account, and can only be used with one account at a time. In these cases, Link will present a single account selection flow, regardless of your customization settings.

After a user selects their accounts and clicks **Continue**, the Connected pane will be shown. The selected accounts will be specified in the [accounts](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts) property of the `onSuccess()` callback.

```javascript
const onSuccess = useCallback(
 (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
   // updated selected account ids
   const account_ids = metadata.accounts.map(account => account.id);
   // ...
 },
 [],
);
```

Only the data for the selected accounts will be available for the accounts via the API. You can listen for [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhooks to discover new accounts for the created Item and use [update mode with Account Select enabled](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) to request data to be shared for new accounts from your users.

For some older Items created before March 2023, data for all accounts may be available, even if the user did not select the account in Account Select, and access to new accounts may be granted without needing to use the update mode flow. If these Items are at OAuth institutions, they will be updated to use the current Account Select behavior when they are sent through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

#### Language and country 

You can select the language Link will appear in, as well as the countries it should support, on the settings pane, accessible via the gear icon in the upper-right corner. The list of countries selected will control which institutions are displayed in Link, as well as whether the OAuth pane will appear. The language setting will determine the default strings used in the Link UI. If you want to customize the translation, you can edit the strings, as described in the Text strings section above.

Language and country are also specified via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , using the [country\_codes](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-country-codes) and `language` parameters. It is important that the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) parameters and customization settings match each other. If the language specified via `language` does not match the language selected for the customization, the customization will not be applied. If the country codes specified via [country\_codes](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-country-codes) do not match the country codes selected for the customization, the country codes selected for the customization may be overridden.

Plaid supports over a dozen languages and countries in Link and is continually adding more. For an up-to-date list of supported languages and countries, see the [Dashboard](https://dashboard.plaid.com/link) or the [API Reference](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-language) .

For Identity Verification, the language Link appears in is instead automatically selected based on the end user's browser settings. For more details, see [Identity Verification supported languages](https://plaid.com/docs/identity-verification/index.html.md#supported-languages) .

#### Color scheme 

You can configure the color scheme used by Link to match your company's brand colors or website color scheme via the **Background Color** setting.

#### Text strings 

You can change the text shown on some of the screens to customize the wording to your app. This setting can be configured via the **Consent**, **Institution Select**, **Institution Search**, **Connected** and **Re-Connected** settings.

#### Financial institutions 

Plaid recommends a default list of financial institutions whose logos are shown on the bank selection screen. This list is personalized based on user data, such as location. This option is automatically enabled; the **Automatic** option is pre-selected in the **Institution Select** setting.

Alternatively, you can customize the list of institutions by choosing the **Custom** option, but this option may result in lower conversion.

#### (Document Income only) Document upload settings 

If you are using the [Document Income](https://plaid.com/docs/income/index.html.md) product, you can use Link customizations to individually enable or disable the different types of documents your customers are allowed to upload in Link. You can configure the following options:

*   What type of document can be uploaded
*   What filetypes of document can be uploaded
*   The minimum and maximum number of documents that can be uploaded

Note that you must have Production access to Document Income before you can configure this setting; it will not appear if your Production access request has not yet been submitted or approved.

#### Data Transparency Messaging 

As of October 31, 2024, all new customers launching in the US and/or Canada must select a use case under the Data Transparency Messaging section of the Link customization UI in order to use Link in Production.

Under the **Data Transparency Messaging** section of the Link customization, you can opt in to Data Transparency Messaging and/or select the use cases that will be displayed in Link during the Data Transparency Messaging flow. For more details, see [Data Transparency Messaging Migration Guide](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) .

#### Consent pane customizations 

##### Overview 

The Consent pane is what users see when first entering Plaid Link and where they consent to the [end-user privacy policy](https://plaid.com/legal/#end-user-privacy-policy) . Plaid offers the option to select whether Plaid branding or a combination of your branding and Plaid’s is featured. This latter option includes the ability to upload a brand color as well as a brand logo.

(An image of "Two consent panes: one with Plaid logo, the other co-branded with WonderWallet. Both outline secure account connection and privacy.")

Plaid-branded Consent pane and Co-branded Consent pane respectively

Headlines are standardized based on which products Link is initialized with.

##### Product-mapped titles 

| Product(s) | Title text |
| --- | --- |
| `assets`, `auth`, `identity`, `investments`, `liabilities`, `transactions` | \[App name\] uses Plaid to connect your \[custom field\] |
| `employment` (beta) | \[App name\] uses Plaid to verify your employment |
| `income_verification` | \[App name\] uses Plaid to verify your income |

This version of the Consent pane is only available to Link customization settings targeting the US and Canada.

##### Customizing the Consent pane 

Within the [Link Customization page](https://dashboard.plaid.com/link) , under the **Consent** section, you can choose to activate the Plaid-branded Consent pane or the co-branded Consent pane.

If you choose the co-branded experience, you will see a box that will guide you to choosing your logo, and if you wish, a brand color that will be used for the animation on the loading screen. You **must** upload a logo (1024 x 1024 .png file) to use the co-branded experience. You can upload a logo or brand color directly within the Consent experience, or you can make the same changes within the Team Settings page.

You can also choose to enable [Data Transparency Messaging (beta)](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) where you can describe your use case for accessing the data types that you are requesting. Note that enabling Data Transparency Messaging on the Consent Pane will prevent your access to products beyond those that you pass to Link. For more information, see [Enabling Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) .

Once you are done configuring your new Consent pane, click **Publish** and your new changes will go into effect.

#### Other customizable settings 

Several other settings exist to configure Link, outside of the customization pane.

##### Account subtype filters 

Account filters allow you to select which account types and subtypes will be available in Link. For example, if you only want users to link a checking account, you can use Link to display only Items that contain checking accounts. This setting will apply to both the Account Select view and the Institution Select view.

Account filters can be configured via the [account\_filters](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-account-filters) parameter when creating a Link token. For details, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

Account types and subtypes that are not compatible with the products used to initialize Link will be automatically omitted and do not require an account filter setting. For details on account type and subtype compatibility, see the [Account type / product support matrix](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) .

##### Institution Select shortcut 

The Institution Select shortcut can be enabled to create a streamlined Link experience for users when you already know which institution the user wants to connect to before initializing Link. For example, this could be the case when migrating to Plaid from an ACH implementation where users manually entered their account and routing number.

You can pass `routing_number` into the `institution_data` request field in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. The matched institution will be listed first in the default list of institutions shown for that session.

If the end user chooses the matched institution, Plaid will send the `MATCHED_SELECT_INSTITUTION` event callback with metadata `{match_reason: routing_number}`.

---


# Link - Data Transparency Messaging migration | Plaid Docs

Data Transparency Messaging Guide 
==================================

#### How to enable and manage Data Transparency Messaging for your application 

As of October 31, 2024, all new Plaid Inc. customers launching to end users in the US and/or Canada are automatically enrolled for Data Transparency Messaging and must [select a use case](https://dashboard.plaid.com/link/data-transparency-v5) to use Link in Production, including Limited Production. This does not apply customers who use only products that don't connect to financial institutions, like Identity Verification, or to customers using only Consumer Report or other Plaid Check products.

#### Introduction 

Plaid has introduced Data Transparency Messaging (DTM) into the Link flow to help you stay in compliance with the [1033 rule](https://plaid.com/resources/compliance/section-1033/) . This experience provides end users (consumers) with a greater understanding of the types of data that they share with you and Plaid. When using DTM, a user is informed of the specific data types that you are requesting and the reason that you are requesting them (use cases). If you want access to additional data from a user after their initial Link, or to use the data for additional use cases, they must consent to sharing that data through a separate consent flow.

This guide covers the implementation changes required to implement the Data Transparency Messaging feature.

(An image of "Plaid's Data Transparency Messaging: Log in at Gingham Bank, disclose account info, select accounts, with product-specific disclosures.")

DTM introduces product-specific disclosures above the "Continue" buttons. If the user clicks the Learn More link within the disclosure, the "Why is this needed" half-pane appears.

##### Who is affected 

Data Transparency Messaging (DTM) will be required for all Plaid customers, unless you meet one of the criteria below:

*   You use only products that don't connect to financial institutions: Identity Verification, Beacon, Monitor, or Enrich.
*   You serve end users only in Europe. If you serve end users in Canada but not the United States and would like to opt out of Data Transparency Messaging, contact your Account Manager.
*   You use only Plaid Check products (i.e. Consumer Report) rather than Plaid Inc. products.

##### What's new 

*   The API will only return data for products that users have consented to through Link. In addition to the existing `products` field, we have added a new configuration field called `additional_consented_products` that can be used to gather consent for additional products.
*   Link can be configured to display DTM. The language will appear as a footer on the OAuth pane (shown to consumers before they are directed to an institution’s OAuth flow), or the Account Select pane for sessions that do not go through OAuth.
*   If enabled via the Plaid Dashboard, DTM must be configured to include at least one use case, which explains to users the purpose of the data being requested. You may choose up to 3 use cases for each Link customization that will be shown in Link to your users. You can select these use cases via the [Dashboard Link Customization page](https://dashboard.plaid.com/link/data-transparency-v5) .
*   Products that require data not consented to by users through Link cannot be accessed without going through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

Data Transparency Messaging is available to all customers who are enabled for US or Canada on an opt-in basis. New customers will be automatically enabled for Data Transparency Messaging, and some existing customers have been automatically enabled for Data Transparency Messaging. For existing customers who have not yet been enabled for Data Transparency Messaging, Plaid will provide more details on the enablement timeline once it has been finalized.

#### Migration overview 

1.  Review your API integration and, if necessary, [populate the additional\_consented\_products field](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#additional-consented-products) with products you want to gather consent for. Every product that you currently use should be included in either the `products`, `optional_products`, `required_if_supported_products` or `additional_consented_products` fields. For more information on the differences between these fields, see [Initializing products](https://plaid.com/docs/link/initializing-products/index.html.md#overview) .
2.  Update the use cases for each Link customization via the [Dashboard](https://plaid.com/docs/link/customization/index.html.md) .
3.  (Optional) [Update Link customizations](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#updating-link-customizations) to enable DTM via the [Dashboard](https://plaid.com/docs/link/customization/index.html.md) .
4.  (Future) Configure [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to renew consent.

#### Additional consented products 

Previously, as long as you were approved and enabled for a product during your Plaid Dashboard Production Request process, you could request and start using it by calling the corresponding product API route on any Item. Going forward, any Item that goes through Link with DTM enabled restricts your access to new product data unless the Item has the required consent; if you do not have the required consent, you will receive the error [ADDITIONAL\_CONSENT\_REQUIRED](https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required) . Additional consent will need to be collected through update mode.

If you need to use a product but don't want Plaid to try to extract that data immediately, you can create a Link token with [additional\_consented\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-additional-consented-products) specified. These products will be shown in Link as part of DTM, but will not be fetched or billed until you request them. Specifying `additional_consented_products` will not have any impact on Items created before DTM is enabled, but it is recommended that you start using this field so you can be ready when DTM is enabled for your Link flows.

The products in the `additional_consented_products` field may not have any overlap with products listed in the `products`, `optional_products` or `required_if_supported_products`. The `products` array must contain at least one product. In the DTM language, Link will show data scopes corresponding to the union of `products`, `optional_products`, `required_if_supported_products`, and `additional_consented_products`.

Products placed in the `additional_consented_products` field do not have any impact on institution filtering or account subtype filtering. For example, if `auth` is an `additional_consented_product`, users will be allowed to select any account, not just checking/savings accounts.

When your existing Items are migrated to DTM, Items in the US or Canada created without DTM will have the following migration applied: the `billed_products`, along with any additional products that use the same data scopes, will be automatically added to the `consented_products` field for those Items. You will be notified when your Items are scheduled to be migrated.

#### Updating Link customizations 

To opt into DTM, go to your [Link customization](https://dashboard.plaid.com/link/privacy-interstitial) or create a new one (you may duplicate an existing customization by using the [duplicate feature](https://plaid.com/docs/link/customization/index.html.md#link-customization-overview) ), click on the Data Transparency section, where you can customize the use case. You must have at least one selected use case to save the customization. You can preview the primary footer language and the detailed panel. This language will appear on the OAuth pane for sessions that go through OAuth, and on Account Select otherwise.

Use cases will only be shown in Link if the end user clicks the "Learn more" link within the DTM disclosure text.

| Category | Use cases |
| --- | --- |
| Payments | Send and receive money, Pay your bills, Make a purchase online, Facilitate business-to-business payments, Fund your account |
| Identity verification and fraud | Verify your identity and prevent fraud, Verify your account, Protect against fraud |
| Personal / Business finance management | Track and manage your finances, Prepare your taxes, Get rewards, Invest your money, Do business accounting and tax preparation, Prepare and categorize invoices, Manage employee expense reporting, Track, manage and build your credit, Access your paycheck sooner, Pay down debt |
| Credit underwriting | Get considered for a loan, Verify your income |

There is no restriction enforced on which use case(s) you select beyond the limit of three use cases per customization. For example, you may still select a payments-related use case even if you are not Production-enabled for any payments-related products and not initializing Link with any payments-related products.

In the Production environment, the use cases you select will also visible to consumers via the Plaid Portal ([my.plaid.com](https://my.plaid.com/) ) and to Plaid financial institution partners.

Once you've selected how you want to present DTM to users and selected at least one use case, click Publish. Your changes will go into effect the next time you initialize Link with this customization. Only newly created Items created with the updated customization will have the new API behavior; existing Items will not be affected.

If you want to prepare for the DTM automatic enablement date without enabling DTM earlier than necessary, you can add use cases to your [Link customization](https://dashboard.plaid.com/link/privacy-interstitial) without enabling DTM.

If you currently use additional products after Link that you do not initialize via the `products` field, it is recommended that you update your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) code to include `additional_consented_products` before enabling this feature in the Plaid Dashboard to avoid losing access to the additional API endpoints on your new Items.

#### Authorization records 

You may need to review authorization records to meet audit requirements or to make decisions about collecting additional consent.

Current authorization details such as an Item's consented products and consented use cases are available via the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) endpoint. These are updated in near real time and may be used to configure update mode to request additional consent from a user.

Historical authorization records are available via [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) . These records will be retained and available for at least 3 years (though the earliest records will begin in November 2024).

Authorization details and historical authorization records will only be available for Items that have been enabled for Data Transparency Messaging.

#### API changes 

For Items that have gone through Link with Data Transparency Messaging enabled, there will be new `consented_products` and `consented_data_scopes` fields returned by the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) endpoint.

You will see the error code [ADDITIONAL\_CONSENT\_REQUIRED](https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required) if you do not have consent to a product you are trying to request. This is the same error you would get if you are not enabled for the product.

To resolve `ADDITIONAL_CONSENT_REQUIRED` errors, you will need to send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) .

#### Data scopes and consent 

The products you request for Link Initialization are not mapped 1:1 with the different data scopes displayed. Our goal is to allow consumers to understand what types of data they are permissioning, and product names alone can be confusing to consumers. Because data scopes can be broad, in certain cases, you will get consent for more than just the products you initialize Link with. For example, the Assets product requires consent to both the "Transactions" and the "Account Holder Information" data scopes, so the Transactions and Identity products will both be consented to by default. To understand which products you have consent to access for a given Item, you can use the `consented_products` field on the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) or product endpoints as detailed above.

Note that the data scopes used by Plaid should not be confused with OAuth data scopes. Some institutions that use OAuth define their own data scopes, and users at OAuth institutions may be required to grant consent to both Plaid's data scopes and institution-specific OAuth data scopes during the Link flow. For more information on OAuth data scopes, see [Scoped consent](https://plaid.com/docs/link/oauth/index.html.md#scoped-consent) in the OAuth documentation.

##### Data scope descriptions 

<table class="Container_table__oZo8c"><tbody><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Account and balance info</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May include account details such as account name, type, description, balances, and masked account number.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Contact info</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May include account owner name, email, phone, and address.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Account and routing number</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">Includes account number and financial institution routing numbers.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Transactions</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May include transaction details such as amounts, dates, price, location, spending categories and descriptions, and insights like recurring transactions.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Credit and loans</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May include details about your credit and loan accounts, such as balance, payment dates and amounts due, credit limit, repayment status, interest rate, loan terms, and originator info.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Bank Statements</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May include account info such as activity and usage, and contact details.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Investments</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May include info about investment accounts, such as securities details, quantity, price, and transactions.</td></tr><tr class="Row_row__4qF91"><td class="Row_description__SSNXH"><div class="Row_title__j0gQ0">Risk info</div><div class="Row_subtitle__8_gRf"></div></td><td class="Row_contents__EJTwh">May use account info such as activity and usage, contact details, transaction-related information, and Plaid connection history to provide an assessment of fraud and/or minimize overdrafts</td></tr></tbody></table>

##### Data scopes by product 

| Plaid Product | Data scopes required |
| --- | --- |
| Account Risk (beta) | Account and balance info, Contact info, Transactions, Risk info |
| Assets | Account and balance info, Contact info, Transactions |
| Auth: Instant Auth or Instant Match | Account and balance info, Contact info, Account and routing number |
| Auth: Database Auth, Database Insights, or Database Match | Account and routing number |
| Auth: Same-Day Micro-deposit or Instant Micro-deposit | Account and routing number |
| Auth: Automatic Micro-deposit | Account and balance info, Contact info, Transactions, Account and routing number |
| Balance | Account and balance info |
| Bank Income | Account and balance info, Contact info, Transactions |
| Consumer Report by Plaid Check | Account and balance info, Contact info, Transactions |
| Statements | Account and balance info, Contact info, Statements |
| Identity (includes Identity Match) | Account and balance info, Contact info |
| Investments | Account and balance info, Contact info, Investments |
| Liabilities | Account and balance info, Contact info, Credit and Loans |
| Signal | Account and balance info, Contact info, Transactions, Risk info |
| Transactions (includes Recurring Transactions) | Account and balance info, Contact info, Transactions |
| Transfer | Account and balance info, Contact info, Account and routing number |
| Investments Move (fka Investments Auth) (beta) | Account and balance info, Contact info, Account and routing number, Investments |

Account and balance info and Contact info are almost always requested; there are some exceptions for products like Database Match or Database Insights where Plaid does not pull data from the bank, and does not require this information.

Plaid will disclose all the underlying data scopes needed to deliver the product. For example, Signal uses Transactions data to derive the Signal risk score, so we disclose that the data scope Transactions was accessed, even if you do not request the product Transactions in `products` or `additional_consented_products`. In this case, Plaid will record the user’s consent to the Transactions data scope. If you request a product requiring the Transactions data scope in the future, you will not need to use update mode. (But if you are adding a new use case as well, you will need to use update mode to request consent for that use case, even if you already have the required product consent.)

Some Plaid products do not have any associated bank data scopes because they do not rely on access to bank data. For example, Identity Verification, Document Income, and Payroll Income do not rely on bank data.

#### Requesting consent for additional products or use cases in update mode 

If you would like to start collecting product data for an Item that you did not collect enough consent for during initial creation, you are able to send that Item through update mode to collect new consent. For details, see [Requesting additional consented products](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) and [Requesting additional use cases](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-use-cases) in the update mode documentation.

#### Automatic migration path 

If you do not choose to follow any of the steps in this guide, your eligible Link sessions (those including a country code of `US` and/or `CA`) will be automatically enabled for Data Transparency Messaging. No date has been finalized for this automatic migration; Plaid will provide details when it has been determined.

When your team is automatically enabled for Data Transparency Messaging, the following migrations will occur:

*   Plaid will enable DTM for your Items and Link flows. If you have not customized your use cases as described in [Updating Link customizations](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#updating-link-customizations) , the use cases presented in the Link UI will be automatically populated based on information you have previously provided to us (e.g. in the Production Request Form).
*   If you do not specify `additional_consented_products` in your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, Plaid will perform an assessment of your historical product add behavior. If, in the last 6 months before the enforcement date, you had billable activity for a product, and that product is not included in the `products`, `required_if_supported_products`, or `optional_products` arrays, Plaid will automatically update your Link session to request consent for that product as though that product had been added to the `additional_consented_products` array. To opt out of this behavior, contact your Account Manager.

DTM is mandatory for all customers who are enabled for Plaid in the US. While Canada-based Link sessions are not subject to 1033 enforcement, they will receive DTM to provide enhanced consumer transparency. If you are enabled for Canada but not for the US and want to opt out of automatic DTM enablement, contact your Account Manager.

#### Minimum client library version for using additional consented products 

*   [Python](https://github.com/plaid/plaid-python/blob/master/CHANGELOG.md) \- 9.3.0
*   [Node](https://github.com/plaid/plaid-node/blob/master/CHANGELOG.md) \- 10.4.0
*   [Ruby](https://github.com/plaid/plaid-ruby/blob/master/CHANGELOG.md) \- 15.5.0
*   [Java](https://github.com/plaid/plaid-java/blob/master/CHANGELOG.md) \- 11.3.0
*   [Go](https://github.com/plaid/plaid-go/blob/master/CHANGELOG.md) \- 3.4.0

---


# Link - Preventing duplicate Items | Plaid Docs

Preventing duplicate Items 
===========================

#### Prevent unnecessary billing and confusing application behavior 

[Watch video](https://www.youtube.com/watch?v=6wWPKrVPaio)

#### How duplicate Items are created 

An [Item](https://plaid.com/docs/quickstart/glossary/index.html.md#item) represents a login at a financial institution. This login typically happens when an end user links an account (or several accounts) using [Plaid Link](https://plaid.com/docs/link/index.html.md) . A duplicate Item will be created if the end user logs into the same institution using the same credentials again using Plaid Link (in the same application), and if an access token is requested for the Item.

Duplicate Items can occur for multiple reasons. For example, a duplicate Item can occur if a user accidentally links the same account more than once, because they do not realize they already linked an account, or because their linked account is no longer working. Duplicate Items can also occur if a user intentionally links multiple Items for abusive purposes (for example, as part of an attempt to receive multiple sign-up bonuses or to evade a ban).

Duplicate Items can create confusing or unwanted behavior in your application, can sometimes be a vector for fraud and abuse, and may cause you to be charged multiple times for the same Item. We recommend building safeguards in your application to help prevent end users from creating duplicate Items. In this article, we'll describe a few ways to prevent and detect Item duplication.

#### Preventing duplicate Items 

##### Use the onSuccess callback metadata 

The [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback is called when a user successfully links an Item using Plaid Link. This callback provides metadata that you can use to prevent duplicate Items from being created. (Alternatively, if you're using a connection method that does not provide data in the `onSuccess` callback, such as Hosted Link, you can obtain this metadata by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) and using the `results.item_add_results` array.) One approach is to require a user login prior to launching Plaid Link so that you can retrieve existing Items associated with the user.

Then, before requesting an `access_token`, examine and compare the `onSuccess` callback metadata to the user's existing Items. You can compare a combination of the accounts’ `institution_id`, account `name`, and account `mask` to determine whether an end user has previously linked an account to your application. Do not exchange a public token for an access token if you detect a duplicate Item.

While the `mask` value is usually the same as the last 4 digits of the account number, this is not the case at all institutions. Never detect duplicate Items by attempting to match a `mask` with an account number.

```javascript
{
  institution: {
    name: 'Wells Fargo',
    institution_id: 'ins_4'
  },
  accounts: [
    {
      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
      name: 'Plaid Checking',
      mask: '0000',
      type: 'depository',
      subtype: 'checking',
      verification_status: ''
    },
    {
      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
      name: 'Plaid Saving',
      mask: '1111',
      type: 'depository',
      subtype: 'savings'
    }
    ...
  ],
  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
}
```

Note that duplicate Items are not always identical. For example, an Item may have a checking account linked, while its duplicate may have only a savings account linked. While this scenario is rare, if it becomes a problem for your use case, you can switch to using the `institution_id` field on a per-user basis to prevent duplicate Items and enforce that each user of your app not link multiple Items with the same institution. However, because this is a legitimate use case for some applications, it is not recommended as the primary means of detecting duplicate Items.

Duplicate Items at Chase, PNC, NFCU, and Schwab

For Chase, PNC, Navy Federal Credit Union, and Charles Schwab, existing Items may be invalidated if an end user adds a second Item using the same credentials, at the point when the user has completed the institution's OAuth flow. At Chase, this will only happen if the second Item does not have exactly the same set of accounts associated as the first Item (i.e. the user granted permissions to different accounts in the institution's OAuth flow) or if either of the Items is initialized with a [Plaid Check product](https://plaid.com/docs/check/index.html.md) .

If this occurs, delete the old Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and use the new Item. Alternatively, the old Item can repaired using [update mode](https://plaid.com/docs/link/update-mode/index.html.md) , which will invalidate the new Item. Then you may delete the new Item.

For Auth or Transfer customers, Chase or PNC Item invalidation caused by creating a duplicate Item will not invalidate or change the Item's TAN.

##### Implement Pre-Link messaging 

A lightweight but effective method for preventing accidental duplicate Items from being created is by providing relevant messaging and information to end users before they engage with Plaid Link in your application. For example, displaying a list of accounts they've already connected to your application can help prevent end users from inadvertently linking the same accounts again.

##### Use Link's update mode 

From time to time, an Item may become unhealthy due to entering the `ITEM_LOGIN_REQUIRED` state. Or, the Item may still be healthy, but you may want your end user to authorize additional accounts or permissions associated with the Item. When either of these scenarios happens, use [Link in update mode](https://plaid.com/docs/link/update-mode/index.html.md) to refresh the Item instead of creating a new Item.

#### Example implementation: Preventing accidental duplicate Items 

For an example that demonstrates how to prevent accidental duplicate Items, see the [Plaid Pattern](https://github.com/plaid/pattern) sample app. Plaid Pattern implements simple server-side logic to check whether the user ID and institution ID pair already exist in the application database. If the pair exists, an access token will not be requested for this Item, thereby preventing a duplicate. In addition, a message is displayed to the end user informing them that they've already linked this Item. The relevant code can be found in [/server/routes/items.js](https://github.com/plaid/pattern/blob/master/server/routes/items.js#L41-L49) and [/server/db/queries/items.js](https://github.com/plaid/pattern/blob/master/server/db/queries/items.js#L73-L88) .

#### Identifying existing duplicate Items 

To identify existing duplicate Items, use the same matching logic as described above, but retrieve this data via the [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint instead of the `onSuccess` callback. Occasionally, the `mask` or `name` fields may be null, in which case you can compare `institution_id` and `client_user_id` as a fallback. After identifying duplicate Items, use the [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) endpoint to delete an Item.

If you are using Auth via [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , existing duplicate Items may be detected by using the account and routing number fields and looking for duplicates. This method will not work for Items at institutions that use [Tokenized Account Numbers (TANs)](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . To detect existing duplicate Items at these institutions, you can use the [persistent\_account\_id](https://plaid.com/docs/api/accounts/index.html.md#accounts-get-response-accounts-persistent-account-id) field, which will be the same across duplicate instances of the Item.

#### Detecting and preventing duplicate Items across user accounts 

When attempting to detect or prevent duplicate Items, your approach should depend on the type of duplicate Item you are trying to prevent. For example, you can often scope your search to either a single user's accounts, or to all accounts known to your application. If you are attempting to prevent accidental duplicate Items, you should scope the search to a single user; if you are attempting to detect or prevent abuse, it may make more sense to expand your search to all accounts that have been linked to your app.

Note that there can be legitimate use cases for the same financial institution account to be linked across multiple different user accounts (for example, family members who share a joint bank account, or employees of the same company who share access to a business account); depending on your use case, you may want to incorporate this data into a broader abuse detection framework rather than blocking all duplicate accounts.

---


# Link - Embedded Link | Plaid Docs

Link Embedded Institution Search 
=================================

#### Enhance conversion by embedding institution search directly into your app 

With Embedded Institution Search (also known as Embedded Link), you can provide a more seamless transition to the account connectivity experience. For payment experiences in particular, embedding institution search can help guide users to choosing their bank account as a payment method.

[Watch video](https://www.youtube.com/watch?v=TqUo9z-r3x8)

Embedded Institution Search and [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) are both designed to increase adoption of ACH payment methods and are frequently used together. Embedded Institution Search is also fully compatible with other Auth flows, including micro-deposit based flows.

It is highly recommended to use Embedded Institution Search for Link to increase uptake of pay-by-bank if your use case involves a pay-by-bank payments flow where the end user can choose between paying via a credit card and paying via a bank account. If your use case is an account opening or funding flow that requires the customer to use a bank account, or has a surcharge for credit card use, use the standard Link experience instead.

In order to realize the benefits of Embedded Institution Search, you must show it by default when the payments view loads, without requiring the user to first select 'Pay by bank'. If you cannot do this, use the standard Link experience instead.

Embedded Institution Search can be used with the following products: Auth, Identity, Balance, Signal, Transfer, Transactions, Investments, Assets, Liabilities, and all Plaid Check Consumer Report products.

Embedded Institution Search is not compatible with [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . Embedded Institution Search sessions will not be reported in [Link Analytics](https://plaid.com/docs/link/measuring-conversion/index.html.md#link-analytics) .

For recommendations on how to improve the uptake of pay-by-bank and optimize your Embedded Institution Search UX, see [Increasing Pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) .

#### Institution Search user experience 

The user will be able to select from a set of institution logos. This set of logos is customized based on user data, such as location. Alternatively, you can choose which logos will be displayed via the Plaid Dashboard. If a user selects an institution, they will be taken to Link to connect their account.

(An image of "Payment options screen with monthly plan selected, pay by bank method, search bar, and bank logos. Pay button at the bottom.")

Example of Embedded Institution Search on Desktop

(An image of "Mobile flow showing institution search, login to Gingham Bank, and success confirmation via Plaid for payment setup.")

Example of Embedded Institution Search flow on mobile when user selects an institution

If the user's institution is not one of the featured institutions, they can search for their institution using the search bar.

(An image of "Search for a bank in the checkout payment method section using the search bar or select from listed institutions; option to connect manually.")

Example of searching for an institution in Embedded Institution Search on desktop

#### Returning user experience 

The Embedded Institution Search experience can be further optimized for users who have already connected a financial account with Plaid.

(An image of "Returning user form in Embedded Institution Search with fields for name, address, city, state, and zip code, and a 'Continue' button.")

Example of the returning user experience in Embedded Institution Search

When a user's device is recognized or the phone number is provided via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , Plaid will check to see if they are a returning user. If they are detected as a returning user, Link will run a security check on the session in the background. If this check passes, the user will be shown a list of previously connected accounts in the embedded module.

The user can then verify their phone number using a one-time password and complete the account linking process if the previously linked institutions do not require re-authentication. For more details on the returning user flow, see [Returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) .

Note that if Plaid Check Consumer Report products are included in the Link token request, then returning users will see the default Institution Search user experience.

##### Testing in Sandbox 

In order to test the returning user experience in Embedded Institution Search, use the phone numbers listed in [Testing returning user experience in Sandbox](https://plaid.com/docs/link/returning-user/index.html.md#testing-in-sandbox) .

#### Integration steps 

Embedded Institution Search is available for all supported integration modes except webviews and Hosted Link. Embedded Institution Search cannot be rendered inside an iFrame.

Before integrating, make sure you are using a version of the SDK that supports Embedded Institution Search.

| Platform | Minimum SDK version required |
| --- | --- |
| [Android](https://github.com/plaid/plaid-link-android) | 3.14.0 |
| [iOS](https://github.com/plaid/plaid-link-ios) | 4.5.0 |
| [React Native](https://github.com/plaid/react-native-plaid-link-sdk) | 10.6.0 |
| [React web](https://github.com/plaid/react-plaid-link) | 3.5.1 |
| JavaScript web | N/A (all customers are on the latest version) |

1.  Create a Link token as normal, using [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; no special parameters are required when making this call to enable Embedded Institution Search. The 'Connect Manually' button rendering is configured with the `auth_type_select_enabled` boolean in the `auth` object.
2.  Create an embedded view. This should be done before it will be displayed in your app, to minimize latency. Plaid will track when this view is requested and activate the Embedded Search UI. If you are using iOS, call `createEmbeddedView`, which will return a Result containing a `UIView`. Once you have the `UIView`, add it to your `ViewController`'s view. If you are using the web SDK, call `Plaid.createEmbedded` instead of `Plaid.create` to open Link. For other platforms, you will create the view as normal.
3.  Lay out the view Plaid returns from the configuration. Using a **minimum size of 350x300px or 300x350px** is strongly recommended. Smaller sizes will significantly degrade conversion. If you are migrating to Embedded Institution Search from traditional Link, delete your old Link presentation in favor of this new one.

Select group for content switcher

iOSAndroidJavaScriptReact

```clike
private func setupEmbeddedSearchView(token: String) {


        // Create a configuration like normal.
        var configuration = LinkTokenConfiguration(
            token: token,
            onSuccess: { success in
                print("success: \(success)")
            }
        )


        configuration.onEvent = { event in
            print("Event: \(event)")
        }


        configuration.onExit = { exit in
            print("Exit: \(exit)")
        }


        // Create a handler with your configuration like normal.
        let handlerResult = Plaid.create(configuration)
        switch handlerResult {
        case .success(let handler):


            // Save a reference to your handler.
            self.handler = handler


            // Create an embedded view.
            let embeddedSearchView = handler.createEmbeddedView(presentUsing: .viewController(self))


            // Layout this view
            embeddedSearchView.translatesAutoresizingMaskIntoConstraints = false
            view.addSubview(embeddedSearchView)


            NSLayoutConstraint.activate([
                embeddedSearchView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 8),
                embeddedSearchView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 25),
                embeddedSearchView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -25),
                embeddedSearchView.heightAnchor.constraint(equalToConstant: 360),
            ])




        case .failure(let error):
            // Error creating handler. Handle like normal.
            fatalError("\(error)")
        }
    }
```

```typescript
// Register a callback for an Activity Result like normal (must be done from an Activity)
 private val linkAccountToPlaid =
   registerForActivityResult(OpenPlaidLink()) { result ->
      when (result) {
        is LinkSuccess -> /* handle LinkSuccess */
        is LinkExit -> /* handle LinkExit (from LinkActivity) */
      }
    }


// Create a linkTokenConfiguration like normal
val linkTokenConfiguration = LinkTokenConfiguration.Builder().token(token).build()


// Create the view with a trailing lambda for handling LinkExits from the Embedded View
val embeddedView = Plaid.createLinkEmbeddedView(
this /*Activity context*/,
linkTokenConfiguration,
linkAccountToPlaid) {
exit: LinkExit -> /* handle LinkExit (from Embedded View) */
  }
)


// Add this embeddedView to a view in your layout
binding.embeddedViewContainer.addView(embeddedView)
```

```javascript
// The container at `#plaid-embedded-link-container` will need to be sized in order to
// control the size of the embedded Plaid module
const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container');


Plaid.createEmbedded(
    {
      token: 'GENERATED_LINK_TOKEN',
      onSuccess: (public_token, metadata) => {},
      onLoad: () => {},
      onExit: (err, metadata) => {},
      onEvent: (eventName, metadata) => {},
    },
    embeddedLinkOpenTarget,
);
```

```javascript
import React, { useCallback } from 'react';
import { PlaidEmbeddedLink } from 'react-plaid-link';


const App = props => {
  const onSuccess = useCallback(
    (token, metadata) => console.log('onSuccess', token, metadata),
    []
  );


  const onEvent = useCallback(
    (eventName, metadata) => console.log('onEvent', eventName, metadata),
    []
  );


  const onExit = useCallback(
    (err, metadata) => console.log('onExit', err, metadata),
    []
  );


  const config = {
    token: "plaid-token-123",
    onSuccess,
    onEvent,
    onExit,
  };


  return (
    
  );
};


export default App;
```

For an end-to-end example app, see the [Transfer Quickstart](https://github.com/plaid/transfer-quickstart/) , which incorporates Embedded Institution Search in a JavaScript frontend.

##### Update mode 

Embedded Institution Search cannot be used in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) ; to update a user's Item, launch a regular update mode session instead.

#### Customization Options 

You can customize the Embedded Institution Search user experience to match your application's needs.

##### Module responsiveness and tile count 

The embedded Link module will responsively scale to display between two and fifteen institutions, depending on the height and width of the module. Using a **minimum size of 350x300px or 300x350px** is strongly recommended, as smaller sizes degrade conversion particularly on returning user flows. Testing both embedded search and returning user experiences at your chosen module size to ensure usability is also strongly recommended.

On the web, the embedded Plaid module will attempt to use 100% of the height and width of its container. To modify the size of the Plaid module, or to render the Plaid module responsively, you should set the size of the container.

Plaid recommends using the largest container that will comfortably fit in your UI. The larger the container, the more institution logos will be shown. Users are more likely to adopt pay-by-bank when they see their institution's logo on the embedded Link screen.

##### Customizing institutions displayed 

The institutions displayed in Link Embedded Search are based on your [Institution Select settings](https://dashboard.plaid.com/link/institution-select) , which you can optionally customize in the [Dashboard](https://dashboard.plaid.com/link/institution-select) . For most customers, it is recommended to use the default settings.

Embedded Institution Search is compatible with the [Institution Select Shortcut](https://plaid.com/docs/link/customization/index.html.md#institution-select-shortcut) : If you already know which institution the user wants to connect to before initializing Link, you can pass `routing_number` into the `institution_data` request field in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. The matched institution will be listed first (top left position) in the embedded institution grid.

#### Event callbacks emitted by Embedded Institution Search 

###### User chooses an institution directly from embedded search 

*   `onEvent: OPEN` – `view_name: "CONSENT"`
*   `onEvent: SELECT_INSTITUTION`
*   `onEvent: TRANSITION_VIEW` – `view_name: "CONSENT"`
*   `onEvent: TRANSITION_VIEW` – `view_name: "CREDENTIAL" or "OAUTH"` - user selects Continue on the ConsentPane

#### UI Recommendations for Embedded Institution Search 

See [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for recommendations on displaying Embedded Institution Search within your app for pay-by-bank use cases.

---


# Link - Handling an invalid Link Token | Plaid Docs

Handling an invalid Link Token 
===============================

#### Catch the error in the onExit callback and refetch a new link\_token for the next time the user opens Link 

Occasionally, the end user may invalidate the existing `link_token` that was used to open Link by taking too long to go through the flow (30+ minutes), or attempting too many invalid logins. If this happens, Link will exit with an [INVALID\_LINK\_TOKEN](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_link_token) error code.

To allow your user to open Link again, recognize the error in the `onExit` callback, fetch a new `link_token`, and use it to reinitialize Link. You can obtain a new `link_token` by making another [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request:

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

For the Link web integration, reinitializing Link means creating a new iframe. To avoid stacking iframes for each Link initialization, you can clean up the old iframe by calling the [destroy()](https://plaid.com/docs/link/web/index.html.md#destroy) method on the Plaid Link handler.

```javascript
// Initialize Link with a new link_token each time.
const configs = {
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
  },
  onExit: (err, metadata) => {
    // The user exited the Link flow with an INVALID_LINK_TOKEN error.
    // This can happen if the token expires or the user has attempted
    // too many invalid logins.
    if (err != null && err.error_code === 'INVALID_LINK_TOKEN') {
      linkHandler.destroy();
      linkHandler = Plaid.create({
        ...configs,
        // Fetch a new link_token because the old one was invalidated.
        token: (await $.post('/create_link_token')).link_token,
      });
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  },
};


let linkHandler = Plaid.create(configs);
```

When the user is ready, they will be able to reopen Link and go through the authentication process again.

---


# Link - Hosted Link for embedded clients | Plaid Docs

Hosted Link for embedded clients 
=================================

#### Hosted Link integration for PSPs and embedded clients 

#### Overview 

Some customers may not have apps themselves, but instead are embedded within other apps. For example, a payment service provider (PSP) may build a checkout flow which provides several payment options, one of which is pay by bank powered by Plaid. This checkout flow is then used by the PSP's customers within their apps. For these embedded clients, Hosted Link is the recommended approach. This guide will cover implementing [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) specifically for the embedded client use case, covering integration aspects that are unique to this scenario.

While not all customers who use the embedded flow are necessarily PSPs, for the sake of readability, this guide will refer to the client that is embedded within a third party app as the PSP, and the app that they are embedded within as the merchant.

Hosted Link has the following benefits for PSPs:

*   **Simplicity:** Hosted Link is the easiest way to integrate with Plaid when Plaid's native mobile SDKs cannot be used.
*   **Continuity:** With Hosted Link, Plaid manages the redirects between Plaid Link and the bank’s OAuth site. Configuring redirects to a merchant app may not be possible for some PSPs, so Hosted Link ensures the Link session can be completed wherever it is opened.
*   **Easier access to Link callbacks and events:** When Link is launched via Plaid SDKs, Link events and metadata, including the public token, are typically returned via frontend callbacks. With Hosted Link, Link events are returned via backend API calls, making it easier to access information about the Link session without owning the frontend experience.

#### Overview of Hosted Link flow for embedded clients 

##### In-app embeds 

Hosted Link URLs are required to be opened in a secure context such as an `ASWebAuthenticationSession` on iOS or a Chrome Custom Tab on Android. Setting `hosted_link.is_mobile_app` to `true` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) will indicate to Plaid that Hosted Link is being opened in a secure webview, so that Plaid will use the correct redirects.

##### Webpage embeds 

If the flow is embedded in a webpage, there are two options for handling the Hosted Link URI.

###### Redirecting to Hosted Link 

The merchant can redirect their entire page to the Plaid Hosted Link URI. Upon the user completing Link, Plaid will redirect that webpage to the `completion_redirect_uri` provided in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

###### Opening Hosted Link in a new window or tab 

The merchant can open the Plaid Hosted Link URI in a new tab (for mobile web), or pop-up (for desktop web). This allows the user to link with Plaid while keeping the context of the checkout flow behind the pop-up. Upon completion, Plaid can close this pop-up / new tab, bringing the user back to the merchant checkout flow.

#### Hosted Link integration modes 

There are two main types of flows that an embedded app may use. The instructions for integrating Hosted Link will be different for each type, so to integrate with Hosted Link, you will need to identify which one your app uses.

##### With intermediary steps 

In the first type of flow, with intermediary steps, an end user is taken from the merchant to an intermediary page that is controlled directly by the PSP, where they will typically pick a payment method, complete the payment, and then be returned to the intermediary page, which will redirect the end user back to the merchant.

This flow provides slightly more complexity for the end customer, but does not require any additional integration work from the merchant.

##### Without intermediary steps 

In the second type of flow, without intermediary steps, the end user never goes to a page controlled by the PSP. Instead, they will go directly from the merchant's app to the payment method, then return to the merchant's app.

This flow is simpler from the end customer's perspective, but may require additional integration steps by the merchant.

#### Integration process with intermediary steps 

Follow the instructions for using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) . In the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, the `hosted_link.completion_redirect_uri` should be set to your website, which will then handle the process of redirecting the user back to the merchant page.

#### Integration process without intermediary steps 

Follow the instructions for using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) , and see the sections below for instructions specific to the embedded client flow.

##### Completion redirect URIs 

If you would like Plaid to redirect directly to the merchant app, you will use a separate `completion_redirect_uri` for each merchant, each of which must be added to the [Dashboard](https://dashboard.plaid.com/developers/api) .

As an alternative, you may want the `completion_redirect_uri` to be a single URL that you host yourself, and manage the redirects back to merchant apps independently of Plaid. This way, you do not need to add each of the merchant’s redirect URIs to the Plaid Dashboard.

If no `completion_redirect_uri` is provided, the user will see a "Return to app" message on a Plaid.com domain in the browser and must manually navigate back to the merchant app.

###### Merchant integration steps 

Because the application controls how URLs are handled, the merchant may need to add code to their app to open the Plaid hosted Link within the default browser, especially if the PSP's page is opened from within a webview.

[Example function for Android](https://github.com/plaid/plaid-link-examples/blob/master/webviews/android/LinkWebview/app/src/main/java/com/example/linkwebview/MainActivity.kt#L94-L157)

[Example function for iOS](https://github.com/plaid/plaid-link-examples/blob/master/webviews/wkwebview/wkwebview/LinkViewController.swift#L56-L72)

---


# Link - Hosted Link | Plaid Docs

Hosted Link 
============

#### Integrate with Link using a Plaid-hosted frontend 

#### Overview 

Hosted Link is the easiest and fastest way to integrate with Plaid. With Hosted Link, Plaid hosts the Link experience. Customers can use this link in web browsers or open it in a secure web context within a mobile app, eliminating the need for front-end implementation work. Hosted Link is especially recommended for any mobile integration that is not using the official Plaid SDK. If your Plaid integration uses webviews, we strongly recommend switching to Hosted Link. Hosted Link can also be used to complement in-person interactions; for example, you can send a Hosted Link session to customers who are in-person at a retail location.

(An image of "image of Hosted Link flow")

Example hosted Link flow: you send a link to your customer and they complete the Plaid-hosted Link flow. You do no front-end integration work.

With Link Delivery (beta), Hosted Link can also deliver the URL for the Link session to your users via text or email.

Hosted Link is fully supported with all Plaid products and Link flows (including [update mode](https://plaid.com/docs/link/update-mode/index.html.md) ), except for Layer and Identity Verification.

For Identity Verification customers, Hosted Link can optionally be used instead of IDV-specific [Verification Links](https://plaid.com/docs/identity-verification/index.html.md#verification-links-hosted-flow) to take advantage of features such as Link Delivery (beta); however, when using Hosted Link with Identity Verification, the session will not redirect to the `completion_redirect_uri`.

Hosted Link is the preferred frontend integration method for all platforms in which Plaid's native mobile or web SDKs can't be used, including webview-based mobile apps and integrations by embedded clients such as PSPs. For details on using Hosted Link as an embedded client, See [Hosted Link for embedded clients](https://plaid.com/docs/link/hosted-link/embedded-clients/index.html.md) .

##### Benefits of using Hosted Link 

*   **Simplicity**: Hosted Link is the easiest way to integrate with Plaid if you are unable to use Plaid's native mobile SDKs. You don't need to build or maintain a front-end component.
*   **Integration complexity**: Since Hosted Link controls the redirections that are required to support OAuth, it removes one complex step to supporting embedded integrations.
*   **SDK size**: Since the flow will be hosted by Plaid, there is no added SDK size to your application.
*   **Link Recovery**: Hosted Link is required to enable [Link Recovery (beta)](https://plaid.com/docs/link/link-recovery/index.html.md) . With Link Recovery, users whose Link sessions failed due to temporary institution outages can be automatically notified when the issue has been healed, allowing you to increase Link conversion. For more details, see [Link Recovery](https://plaid.com/docs/link/link-recovery/index.html.md) .

To request access to Link Delivery, contact your Account Manager.

#### Integration process 

[Prefer to learn by watching? Check out this quick video guide to enabling Hosted Link!](https://www.youtube.com/watch?v=7wETps5G04A)

##### Creating a Link token 

To start with Hosted Link, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and include a `hosted_link` object in the request. The `hosted_link` object can be an empty object `{}`, or it can contain any of the `hosted_link` configuration fields. As long as you include the `hosted_link` object in your request, the `hosted_link_url` will be present in the response.

Previously, Hosted Link was enabled via Plaid Account Managers; it is no longer necessary to request that your Account Manager enable Hosted Link. If your account was enabled for Hosted Link via your Account Manager, the `hosted_link_url` will be present in the response for all [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests, regardless of whether you include a `hosted_link` object.

You can provide the following Hosted Link parameters to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) :

*   Specify a `webhook` endpoint where the `public_token` will be delivered. Webhooks are strongly recommended when using Hosted Link, as the webhook is the primary means of delivering the `public_token`, as well as of informing you when your user has completed the Link session.
*   To have Plaid deliver the link to your user with Link Delivery (beta), set `hosted_link.delivery_method` to either `sms` or `email`. Plaid will contact the user via the information you provide in the `user` object of the request. For example, if you selected `email`, the `user` object in the request must contain an `email_address`.
*   To customize the duration of the Hosted Link token lifetime, set `hosted_link.url_lifetime_seconds`. If you don't set this field, the default lifetime for Hosted Links sent by Plaid via SMS is 24 hours, and for links sent via email, it is 7 days. If Plaid isn't delivering the url, the default lifetime is 30 minutes.
*   To have Plaid redirect the user after they complete the Link flow, set `hosted_link.completion_redirect_uri` to the destination URI.
*   To indicate that the user will be opening the link in a mobile app in an out-of-process webview (i.e., an `AsWebAuthenticationSession` / `SFSafariViewController` or Android Custom Tab), set `hosted_link.is_mobile_app` to `true`.

The response from [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) will include a `hosted_link_url` field. You can send a user to this URL to start the Hosted Link session. Alternatively, if your integration uses both Hosted Link and non-Hosted Link sessions, you can start a non-Hosted Link session using the `link_token` instead.

In a Hosted Link session, you should also store the `link_token` value that gets returned, and make sure to associate it with the internal user ID your application is using for this user. This is the only way to make sure the data that gets returned from the Hosted Link session is associated with the right end-user.

```bash
curl -X POST https://production.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "client_name": "Wonderwallet",
    "country_codes": ["US"],
    "redirect_uri": "{{UNIVERSAL_OR_APP_LINK}}",
    "webhook": "https://wonderwallet.com/webhook_receiver",
    "language": "en",
    "user": {
      "client_user_id": "a57d3304",
      "phone_number": "+19162255887"
    },
  "products": ["auth"],
  "hosted_link": {
    "delivery_method": "sms",
    "completion_redirect_uri": "https://wonderwallet.com/redirect",
    "is_mobile_app": false,
    "url_lifetime_seconds": 900
  }
}
```

```json
{
  "expiration": "2023-08-18T02:08:03Z",
  "hosted_link_url": "https://secure.plaid.com/link/lp9o97618r1r6p93oon62nr025950ro4s3",
  "link_token": "link-production-4b42163e-6e1c-48bb-a17a-e570405eb9f8",
  "request_id": "kNbPMmLxzBObzpt"
}
```

##### Obtaining a public token 

In most other Plaid integration methods, upon completion of the Link flow, your frontend code would receive either an `onSuccess` or `onExit` callback. In Hosted Link, there is no frontend integration required (or possible). You will instead receive information about the Link flow (including the `public_token`) via the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook and the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint.

Each time a user completes a Link flow, Plaid will fire a [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook that contains information about what caused the session to end, as well as the public token if the session completed successfully. In flows where Link is re-initialized after an OAuth redirect, this webhook will fire exactly once, after the user completes the entire Link flow.

```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"
}
```

You can also call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) with the relevant Link token to receive more detailed metadata on sessions started using this Link token. Each Link session includes the time it was started, and (if applicable) the time it finished. Each completed Link session also includes the metadata that would normally be passed to the `onSuccess` or `onExit` callbacks, including the `public_token` for successful sessions.

Detailed session data, including the public token, will also be available from [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) for six hours after the session has completed. In general, it is recommended to use the webhook to obtain the public token, since it will allow you to get the public token more promptly, but you may want to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) if your integration does not use webhooks, or as a backup mechanism if your system missed webhooks due to an outage.

In [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) the `public_token` is present in both the `on_success` object and the `results` object. It is recommended to use the `results` object, as the older `on_success` object does not support the newer [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) option, which allows for multiple public tokens to be returned in a single Link session.

```json
{
  {
    "created_at": "2024-07-29T21:22:13Z",
    "expiration": "2024-07-29T21:52:13Z",
    "link_sessions": [
        {
            "events": [
                {
                    "event_id": "c1ccb962-9de0-494c-b85b-e89cdf3b2478",
                    "event_metadata": {
                        "institution_id": "ins_10",
                        "institution_name": "American Express",
                        "request_id": "Z9MB4fuMB2TJqgL"
                    },
                    "event_name": "HANDOFF",
                    "timestamp": "2024-07-29T21:23:03Z"
                },
                {
                    "event_id": "ff03f1ff-313b-4c2e-997f-83791c7ec432",
                    "event_metadata": {
                        "institution_id": "ins_10",
                        "institution_name": "American Express",
                        "request_id": "vyPamzbGPPsQucO"
                    },
                    "event_name": "OPEN_OAUTH",
                    "timestamp": "2024-07-29T21:22:34Z"
                },
                {
                    "event_id": "0ea6d0df-1bb0-4e4d-bea5-b3731b7536bf",
                    "event_metadata": {
                        "institution_id": "ins_10",
                        "institution_name": "American Express",
                        "request_id": "vyPamzbGPPsQucO"
                    },
                    "event_name": "TRANSITION_VIEW",
                    "timestamp": "2024-07-29T21:22:33Z"
                },
                {
                    "event_id": "e14c7b49-82c4-4f0c-a88a-987a62241d34",
                    "event_metadata": {
                        "institution_id": "ins_10",
                        "institution_name": "American Express",
                        "request_id": "0jjsLDlMl1VaVxU"
                    },
                    "event_name": "SELECT_INSTITUTION",
                    "timestamp": "2024-07-29T21:22:32Z"
                },
                {
                    "event_id": "b9b9f7ce-52bc-470e-801b-b4fa1da98e59",
                    "event_metadata": {
                        "request_id": "0jjsLDlMl1VaVxU"
                    },
                    "event_name": "TRANSITION_VIEW",
                    "timestamp": "2024-07-29T21:22:23Z"
                },
                {
                    "event_id": "e057a92c-eff8-467c-92c2-620109207e87",
                    "event_metadata": {
                        "request_id": "aHnAMiUzk8HrsNn"
                    },
                    "event_name": "SKIP_SUBMIT_PHONE",
                    "timestamp": "2024-07-29T21:22:22Z"
                },
                {
                    "event_id": "f1feedc9-61be-4a42-885c-cb67511473d2",
                    "event_metadata": {
                        "request_id": "aHnAMiUzk8HrsNn"
                    },
                    "event_name": "TRANSITION_VIEW",
                    "timestamp": "2024-07-29T21:22:21Z"
                },
                {
                    "event_id": "f9b49b0b-4259-4a32-860b-653b55ff8736",
                    "event_metadata": {
                        "request_id": "CGTlWrGRd8WaGa2"
                    },
                    "event_name": "TRANSITION_VIEW",
                    "timestamp": "2024-07-29T21:22:20Z"
                }
            ],
            "finished_at": "2024-07-29T21:23:03.326860787Z",
            "link_session_id": "f3c3b8fe-16c6-4670-8f2b-e8d797aa6e9f",
            "on_success": {
                "metadata": {
                    "accounts": [
                        {
                            "class_type": null,
                            "id": "d1rVJdbe1jCE9jE81wlduPlQQejKXeCJnDzyw",
                            "mask": "3333",
                            "name": "Plaid Credit Card",
                            "subtype": "credit card",
                            "type": "credit",
                            "verification_status": null
                        }
                    ],
                    "institution": {
                        "institution_id": "ins_10",
                        "name": "American Express"
                    },
                    "link_session_id": "f3c3b8fe-16c6-4670-8f2b-e8d797aa6e9f",
                    "transfer_status": null
                },
                "public_token": "public-sandbox-d1e64436-f033-4302-a469-b90656edf8c7"
            },
            "results": {
                "item_add_results": [
                    {
                        "accounts": [
                            {
                                "class_type": null,
                                "id": "d1rVJdbe1jCE9jE81wlduPlQQejKXeCJnDzyw",
                                "mask": "3333",
                                "name": "Plaid Credit Card",
                                "subtype": "credit card",
                                "type": "credit",
                                "verification_status": null
                            }
                        ],
                        "institution": {
                            "institution_id": "ins_10",
                            "name": "American Express"
                        },
                        "public_token": "public-sandbox-d1e64436-f033-4302-a469-b90656edf8c7"
                    }
                ]
            },
            "started_at": "2024-07-29T21:22:17.0951134Z"
        }
    ],
    "link_token": "link-sandbox-9b48eb4c-7e1b-44e1-b80d-faa1d71cdf5e",
    "metadata": {
        "client_name": "Wonderwallet",
        "country_codes": [
            "US"
        ],
        "initial_products": [
            "transactions"
        ],
        "language": "en",
        "redirect_uri": null,
        "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e"
    },
    "request_id": "jBBxxNC842EJNqW"
}
```

#### Link session events 

To obtain Link session events while using Hosted Link, listen for the [EVENTS](https://plaid.com/docs/api/link/index.html.md#events) webhook, or use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) .

#### Integrating Hosted Link in native mobile applications 

If you are unable to use the Plaid Link SDK in your native mobile app, creating and opening up a Hosted Link is a stable and reliable way of taking users through the Link process. We recommend using a Hosted Link instead of trying to use the Plaid Web SDK in a webview.

When you use a Hosted Link in a native mobile app, you will open the URL inside of an "out of process" webview, such as an `ASWebAuthenticationSession` in iOS, or an Android Custom Tab. These sessions appear as part of your application, making the process feel more seamless than opening up the URL in a separate browser application.

When the Link session is complete, Plaid will attempt to open a `completion_redirect_uri` that you specify. This is typically a URI with a custom scheme that automatically closes the web session and allows your application to continue from where you left off.

To use Hosted Link in a native mobile application:

##### Create a Link token 

Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the following values:

*   `hosted_link.is_mobile_app` should be set to `true`
*   `hosted_link.completion_redirect_uri` should be a URI with a custom scheme.
    *   This scheme can be any value you'd like, as long as it isn't a reserved one such as `http` or `tel`. By convention, it's often one associated with the name of your application.
    *   For example, your app might have something like `wonderwallet://hosted-link-complete` as a completion redirect URI.
    *   Unlike the `redirect_uri` value, this URI does not need to be registered with the Plaid Dashboard, nor does it need to point to a "real" location.
*   `redirect_uri` should ideally be a URL that opens up your native mobile application, such as a Universal Link on iOS or an Android App Link on Android.
    *   The `redirect_uri` is used in situations where Plaid opens up another mobile app, like Chase, for app-to-app authentication.
    *   When the user is done authenticating with the third party app, the app will attempt to open this URI, which should redirect users back into your app.
    *   Plaid cannot use `android_package_name` to perform the OAuth redirect when using Hosted Link. You must use `redirect_uri`, even if using an Android app.
    *   There is nothing you need to do to handle this incoming `redirect_uri`. As long as the link opens your application, the Hosted Link session can take it from there.

```bash
curl -X POST https://production.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
     ...Other data removed...
      hosted_link: {
        completion_redirect_uri: "wonderwallet://hosted-link-complete",
        is_mobile_app: true
      },
      redirect_uri: "https://mysite.com/universal-link/jump-to-my-app.html",
}'
```

##### "Register" your custom URL scheme 

You will need to make sure your operating system can handle the completion redirect URI that the Hosted Link session will open when it's complete.

On iOS, all you need to do is pass this URL scheme into the `ASWebAuthenticationSession` when you initialize it (see [Open the Hosted Link URL](https://plaid.com/docs/link/hosted-link/index.html.md#open-the-hosted-link-url) ). There is no need to register this URL scheme in your Xcode project in any other way.

In Android, you should create an Intent Filter for the activity that you want to appear when the user is done with the session.

If this activity is the same activity that you used to launch Hosted Link in the first place, you may want to give this activity a `singleTask` or `singleTop` launch mode, so that the original activity "pops back" to the top of your application, and you're not creating multiple copies of the same activity.

##### Open the Hosted Link URL 

On iOS, create an `ASWebAuthenticationSession`, using the Hosted Link URL you received from the server and the same custom scheme you used in your `completion_redirect_uri`.

```clike
@IBAction func connectBankWasPressed(_ sender: Any) {
    guard let hostedLinkURL = hostedLinkURL else {return}
    let scheme = "wonderwallet"        
    let session = ASWebAuthenticationSession(url: URL(string: urlToOpen)!, callbackURLScheme: scheme) { callbackURL, error in
        guard error == nil, let callbackURL = callbackURL else { 
            // The user might have clicked "Cancel" on the session. This will be captured as a 'canceledLogin' error.
            return 
        }
        if (callbackURL.absoluteString == "\(scheme)://hosted-link-complete") {
            self.checkLinkStatus()
        }
    }
    session.presentationContextProvider = self
    session.start()        
}
```

For the above code to work, you will also need to make sure the appropriate view controller is set as a proper context provider:

```clike
extension ConnectToBankViewController: ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        return view.window!
    }
}
```

On Android devices, create a Custom Tab that opens up the Hosted Link URL from within your application:

```typescript
import androidx.browser.customtabs.CustomTabsIntent
import android.net.Uri


private fun openHostedLink(hostedLinkUrl) {
  val customTabsIntent = CustomTabsIntent.Builder().build()
  customTabsIntent.launchUrl(this, Uri.parse(hostedLinkUrl))
}
```

See the [Apple Developer Documentation](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) or [Chrome Developer Documentation](https://plaid.comhttps://developer.chrome.com/docs/android/custom-tabs/index.html.md) for more details on these two methods.

##### Handle the incoming URI 

When the user is done with the Hosted Link session, Plaid will attempt to open the `completion_redirect_uri` you specified when creating the Link token. If your application is set up as described above, this will close the Hosted Link page and bring your application back to the foreground. You will then receive this URI in a callback handler, where you can perform tasks such as refreshing the user's Link Session status.

The `completion_redirect_uri` is not supported in Identity Verification sessions.

Note that Plaid will call this URI whether the user successfully completed the session, or asked Plaid to exit the connection process, so you cannot assume that receiving this URI means a successful connection. You should listen for the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook or call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to determine the status of the user's Hosted Link session.

On iOS, you define this handler when you create the `ASWebAuthenticationSession`

```clike
let scheme = "wonderwallet"        
let session = ASWebAuthenticationSession(url: URL(string: urlToOpen)!, callbackURLScheme: scheme) { callbackURL, error in
    guard error == nil, let callbackURL = callbackURL else { 
        return 
    }
    if (callbackURL.absoluteString == "\(scheme)://hosted-link-complete") {
        self.checkLinkStatus()
    }
}
```

If the user dismisses the window by clicking the Cancel button, this handler will still be called, but with a `canceledLogin` error instead of a `callbackURL`.

On Android, you can retrieve this URL in the `onNewIntent` callback if you are returning to the previous activity. (If you are opening a new activity, you can use the `onCreate` callback.)

```typescript
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { uri ->
      if (uri.scheme == "wonderwallet" && uri.host == "hosted-link-complete") {
        checkLinkStatus()
      }
    }
  }
```

If the user dismisses the Custom Tab by tapping the close button, this callback will not be called, but an `onResume` callback will still be called.

#### Migrating to Hosted Link from other integrations 

First, review the [Integration process](https://plaid.com/docs/link/hosted-link/index.html.md#integration-process) to understand how to launch the Hosted Link flow and the configuration options available.

If you're currently capturing Link session events, migrate to using [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to receive Link session events.

If your users will be opening Link sessions inside a native mobile application, launch Hosted Link in an out-of-process webview as described above instead of using an in-process webview.

##### iFrame based nested integrations 

For nested integrations like iFrames in a customer web page within a merchant webview, shift from capturing events through redirects to using backend events via [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . Your merchants should launch Hosted Link in an out-of-process webview or external browser.

Either you or the merchant must add an extra callback parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , allowing Plaid to close the out-of-process webview as needed. You will likely make the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. Merchants must either obtain a callback from the customer or ensure handling of a specified callback in their code.

##### Next steps 

Once you have obtained a public token, you can integrate via the same process as non-Hosted Link integrations, including calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the public token for an access token.

#### Testing Hosted Link 

You can test Hosted Link in Production or Sandbox. In the Sandbox environment, Plaid will not provide email or SMS Hosted Link delivery, and update mode sessions will expire after 30 minutes.

#### Pricing 

Hosted Link is free; there is no additional fee to use it. If using Link Delivery to deliver Hosted Link sessions, there is a fee for each link sent. For Link Delivery pricing details, [contact Sales](https://plaid.com/contact/) or your Account Manager.

---


# Link - Overview | Plaid Docs

Link overview 
==============

#### Use Link to connect to your users' financial accounts with the Plaid API 

(An image of "Plaid Link UI workflow: Select bank, enter credentials, and confirm successful account connection with sample customer.")

\=\*=\*=\*=

#### Introduction to Link 

Plaid Link is the client-side component that your users will interact with in order to link their accounts to Plaid and allow you to access their accounts via the Plaid API.

Plaid Link handles all aspects of the login and authentication experience, including credential validation, multi-factor authentication, error handling, and sending account linking confirmation emails. For institutions that use OAuth, Link also manages the OAuth handoff flow, bringing the user to their institution to log in, and then returning them to the Plaid Link experience within your app. Link is supported via SDKs for all modern browsers and platforms, including [web](https://plaid.com/docs/link/web/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , as well as via [React Native](https://plaid.com/docs/link/react-native/index.html.md) , along with community-supported wrappers for [Flutter](https://github.com/jorgefspereira/plaid_flutter) , [Angular](https://github.com/mike-roberts/ngx-plaid-link) , and [Vue](https://github.com/jclaessens97/vue-plaid-link/) .

For webview-based integrations or integrations that don't have a frontend, Plaid also provides a drop-in [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration mode.

To try Link, see [Plaid Link Demo](https://plaid.com/demo/) .

Link is the only available method for connecting accounts in Production and is mandatory for all Plaid integrations. In the Sandbox test environment, Link can optionally be bypassed for testing purposes via [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) .

\=\*=\*=\*=

#### Initializing Link 

Link is initialized by passing the `link_token` to Link. The exact implementation details for passing the `link_token` will vary by platform. For detailed instructions, see the page for your specific platform: [web](https://plaid.com/docs/link/web/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , [mobile webview](https://plaid.com/docs/link/webview/index.html.md) , or [Plaid-hosted](https://plaid.com/docs/link/hosted-link/index.html.md) .

For recommendations on configuring the `link_token` for your use case, see [Choosing how to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) .

\=\*=\*=\*=

#### Link flow overview 

Most Plaid products use Link to generate `public_tokens`. The diagram below shows a model of how Link is used to obtain a `public_token`, which can then be exchanged for an `access_token`, which is used to authenticate requests to the Plaid API.

Note that some products (including Identity Verification, Monitor, Document Income, and Payroll Income) do not use a `public_token` or `access_token`. For those products, you will call product endpoints once the end user has completed Link; see product-specific documentation for details on the flow.

**The Plaid flow** begins when your user wants to connect their bank account to your app.

(An image of "Step diagram")

**1**Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to create a `link_token` and pass the temporary token to your app's client.

(An image of "Step 1 diagram")

**2**Use the `link_token` to open Link for your user. In the [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) , Link will provide a temporary `public_token`. This token can also be obtained on the backend via \`/link/token/get\`.

(An image of "Step 2 diagram")

**3**Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for a permanent `access_token` and `item_id` for the new `Item`.

(An image of "Step 3 diagram")

**4**Store the `access_token` and use it to make product requests for your user's `Item`.

(An image of "Step 4 diagram")

In code, this flow is initiated by creating a `link_token` and using it to initialize Link. The `link_token` can be configured with the Plaid products you will be using and the countries you will need to support.

Once the user has logged in via Link, Link will issue a `public_token`. You can obtain the `public_token` through either the frontend or the backend:

*   On the frontend: From the client-side `onSuccess` callback returned by Link after a successful session. For more details on this method, see the Link frontend documentation for your specific platform.
*   On the backend: From the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint or opt-in `SESSION_FINISHED` webhook after the Link session has been completed successfully. For more details on this method, see the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) documentation.

The `public_token` can then be exchanged for an `access_token` via [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .

\=\*=\*=\*=

#### Supporting OAuth 

Some institutions use an OAuth authentication flow, in which Plaid Link redirects the end user to their bank's website or mobile app to authenticate. To learn how to connect to an institution that uses OAuth, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md) .

\=\*=\*=\*=

#### Customizing Link 

You can customize parts of Link's flow, including some text elements, the institution select view, and the background color, and enable additional features like the Account Select view straight from the [Dashboard](https://dashboard.plaid.com/link) . You can preview your changes in realtime and then publish them instantly once you're ready to go live. For more details, see [Link customization](https://plaid.com/docs/link/customization/index.html.md) .

To help you take advantage of the options available for customizing and configuring Link, Plaid offers a [best practices guide](https://plaid.com/docs/link/best-practices/index.html.md) with recommendations for how to initialize and configure Link within your app.

Link's appearance will also automatically change if the institution selected is not in a healthy state. For more details, see [Institution status in Link](https://plaid.com/docs/link/institution-status/index.html.md) .

\=\*=\*=\*=

#### Returning user flows 

The returning user flow allows you to enable a faster Plaid Link experience for your users who already use Plaid. To learn more, see [Returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) .

\=\*=\*=\*=

#### Error-handling flows 

If your application will access an Item on a recurring basis, rather than just once, it should support [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Update mode allows you to refresh an Item if it enters an error state, such as when a user changes their password or MFA information. For more information, see [Updating an Item](https://plaid.com/docs/link/update-mode/index.html.md) .

It's also recommended to have special handling for when a user attempts to link the same Item twice. Requesting access tokens for duplicate Items can lead to higher bills and end-user confusion. To learn more, see [preventing duplicate Items](https://plaid.com/docs/link/duplicate-items/index.html.md) .

Occasionally, Link itself can enter an error state if the user takes over 30 minutes to complete the Link process. For information on handling this flow, see [Handling invalid Link tokens](https://plaid.com/docs/link/handle-invalid-link-token/index.html.md) .

\=\*=\*=\*=

#### Optimizing Link conversion 

How you configure Link can have a huge impact on the percentage of users who successfully complete the Link flow. To ensure you're maximizing conversion, see [Best practices for Link conversion](https://plaid.com/docs/link/best-practices/index.html.md) .

\=\*=\*=\*=

#### Troubleshooting 

Since all your users will go through Link, it's important to build as robust an integration as possible. For details on dealing with common problems, see the [Troubleshooting](https://plaid.com/docs/link/troubleshooting/index.html.md) section.

\=\*=\*=\*=

#### Link updates 

Plaid periodically updates Link to add new functionality and improve conversion. These changes will be automatically deployed. Any test suites and business logic in your app should be robust to the possibility of changes to the user-facing Link flow.

Users of Plaid's SDKs for React, React Native, iOS, and Android should regularly update to ensure support for the latest client platforms and Plaid functionality.

---


# Link - Choosing when to initialize products | Plaid Docs

Choosing how to initialize products 
====================================

#### Increase conversion and reduce costs by learning how to configure products in Link 

#### Overview 

When you create a Link token, you specify which products to initialize Link with by including those products in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request. Which products you specify in the request parameters will impact many aspects of your Plaid integration, including user conversion, institution availability, the latency your user experiences when connecting their accounts in Link, the latency you experience when retrieving data from the API, and which products you will be billed for.

You can also add products to an Item post-Link, which is discussed below.

[Watch video](https://www.youtube.com/watch?v=yPQPPGdBYIs)

#### Initializing products during Link 

The table below summarizes the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request parameters that determine product initialization in Link:

| Parameter | Required? | Summary | Will Link restrict institutions? | When will Plaid bill me? |
| --- | --- | --- | --- | --- |
| products | Yes | The user must connect an applicable institution and account. | Yes. Only institutions that support all products in this array will be available in Link. | For products billed under a [one-time or recurring fee](https://plaid.com/docs/account/billing/index.html.md) model, you will be billed upon Item creation. |
| required if supported products | No | If the institution supports the products and an applicable account is selected, Plaid will treat these products as required for Item creation to succeed. | No | For products billed under a [one-time or recurring fee](https://plaid.com/docs/account/billing/index.html.md) model, you will be billed upon Item creation. |
| optional products | No | Plaid will pull the data from the institution if possible, but in the event of a failure, Item creation will still succeed. | No | For Auth, Identity, and Signal, you will only be billed if you use the product.  
  
For other products billed under a [one-time or recurring fee](https://plaid.com/docs/account/billing/index.html.md) model, you will be billed upon Item creation. |
| additional consented products | No | Plaid will collect the user's consent to retrieve this data so that if you decide to use this product later on, you won't need to collect the user's consent again. | No | When you call the product endpoint for the first time |

#### Adding products post-Link 

If a product was not initialized during Link, calling an endpoint for that product will automatically attempt to add that product to the Item. For example, if an Item was not initialized with Transactions during Link, calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) or [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) on that Item for the first time will attempt to add the Transactions product to the Item.

Data Transparency Messaging is automatically enabled for all new customers' US and Canada-based Link sessions as of October 2024. On an Item enabled for [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) , you can only add products by calling an endpoint if you specified those products in the Additional Consented Products array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , or if you already have the required [permissions scopes](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#data-scopes-and-consent) for those products.

As another example, if the Item is at an OAuth institution that requires users to grant product-specific access, the end user will need to have granted that access to that product during the OAuth consent flow. To require that users provide all OAuth consent necessary to use a secondary product, use [Required if Supported Products](https://plaid.com/docs/link/initializing-products/index.html.md#required-if-supported-products) instead of adding the product by calling its endpoint post-Link.

If you do not have all the consent required to add a product, your API call attempting to add the product will fail and you will need to send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to obtain that consent.

Some additional exceptions to the post-Link product add flow exist: Identity Verification and Payment Initiation cannot be added post-Link. Assets, Statements, and Bank Income can only be added post-Link via the update mode flow.

#### Impacts of product initialization on latency 

If you initialize Link with a product in the Products, Required if Supported Products, or Optional Products array, Plaid will prepare relevant product data during or immediately after Link. Otherwise, Plaid will only begin to fetch data for that product when you call an endpoint for that product, such as [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . You can minimize product latency by initializing Link with a given product, as opposed to adding the product to the item post-Link.

Products that retrieve extended account history, such as Transactions and Investments, may take a minute or longer to prepare. If you specify one of these products when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , and then you add another product immediately after the user has exited Link, you may experience higher latency when calling the secondary product because the first product is still being prepared.

You can avoid this problem by including the secondary product as either an Optional Product or Required if Supported Product when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , which allows Plaid to optimize how product data is prepared.

#### Impacts of product initialization on billing 

If you initialize Link with a product that is billed under a [one-time or subscription fee](https://plaid.com/docs/account/billing/index.html.md) model (such as Auth, Identity, Income, Investments, Liabilities, or Transactions) you will be billed when the Item is created, even if you are not yet using the product's endpoints. There are exceptions:

*   If you specify Auth, Identity, and/or Signal in the Optional Products array, you will not be billed for them until you use their endpoints (e.g., [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) ).
*   You will not be billed for any products in the Additional Consented Products array until you use their endpoints.
*   Investments has two different subscriptions that can be associated with it: Investments Holdings and Investments Transactions. Initializing Link with Investments adds only Investments Holdings; the Investments Transactions subscription will not be added until you call [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) for the first time on the Item. Note that Plaid will still pre-fetch investment transaction history when you initialize with Investments, even though you are not yet being billed for Investments Transactions.

To avoid unwanted charges, do not initialize Link with a one-time or subscription fee product in Production unless you are sure you are going to use that product. This instruction applies to the Products, Required if Supported Products, and Optional Products arrays, with the exception of Auth, Identity, and Signal when used as Optional Products.

To learn more about how Plaid bills each product, see [Billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Impacts of product initialization on conversion 

The products you specify in the Products array will determine which institutions and accounts are available in Link. If you specify multiple products in the Products array, only institutions and accounts supporting _all_ of those products will be available. See the [accounts / product support](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) matrix to learn which account types support which products.

To avoid overly restricting the institution and account list, you can use the [Required if Supported Products](https://plaid.com/docs/link/initializing-products/index.html.md#required-if-supported-products) or [Optional Products](https://plaid.com/docs/link/initializing-products/index.html.md#optional-products) features, or initialize Link with only your required products in the Products array and then call your other products' endpoints later.

#### Required if Supported Products 

Using the `required_if_supported_products` parameter with a Plaid client library requires the following client library minimum versions: Node: 14.1.0, Python: 14.1.0, Ruby: 19.1.0, Java: 15.1.0, Go: 13.0.0.

You may want to require one or more secondary products when possible, but avoid excluding users whose financial institution doesn't support those products. To do this, specify the secondary products in the Required if Supported Products array.

When a product is specified in the Required if Supported Products array, Plaid will require that product if possible. If the institution the end user is attempting to link supports the secondary product, and the user grants Plaid access to an account at the institution that is compatible with it, Plaid will treat the product as though it was specified in the Products array. If the institution doesn't support the product, if the user doesn't have accounts compatible with it, or if the user has compatible accounts but doesn't grant access to them, Plaid will ignore the product. (To determine whether a product was successfully added to the Item, you can call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) after obtaining your access token and read the Item's Products array.)

For example, if you initialize Link with both Auth and Identity in the Products array, a user will only be able to link an account if both Auth and Identity are supported by their institution, and they will not be able to use flows like Same-day Micro-deposits that require Auth to be initialized by itself. But if you specify Auth in the Products array and Identity in the Required if Supported Products array, users will be able to link checking and savings accounts at any institution that supports Auth, even if the institution does not support Identity. They will also be able to access flows that require Auth to be initialized by itself, like Same-day Micro-deposits.

If the institution _does_ support both Auth and Identity, Plaid will attempt to initialize the Item with both products. If the institution has an OAuth flow where Identity access can be configured as a separate permission, and the user does not grant access to Identity, the Link attempt will error and the user will be prompted to retry the OAuth flow.

As another example, if Transactions and Auth are both specified in the Products array, users will only be able to link checking or savings accounts, because specifying Auth limits acceptable accounts to checking and savings accounts. However, if Transactions is specified in the Products array and Auth is specified in the Required if Supported Products array, users will be able to link other Transactions-compatible account types, such as credit cards and money market accounts. If they do link a checking or savings account, Plaid will fetch Auth data for that account.

#### Optional Products 

Using the `optional_products` parameter with a Plaid client library requires the following client library minimum versions: Node: 17.0.0, Python: 17.0.0, Ruby: 23.0.0, Java: 18.0.0, Go: 17.0.0.

Optional Products is similar to Required if Supported Products, except that products specified in the Optional Products array are treated as _best-effort_. If an institution supports the selected products but they cannot be added to the Item (e.g., because of a temporary institution error impacting only some products, or because the user did not grant the required product-specific OAuth permissions), Item creation will succeed in spite of these failures.

Like the Required if Supported Products array, the Optional Products array does not affect institution filtering or account filtering, which means there are no guarantees around product data availability. For example, if you initialize Link with Transactions in the Products array and Auth in the Optional Products array, the Item is guaranteed to support Transactions, but it will also allow linking account types that are incompatible with Auth, like credit cards.

Unlike Required if Supported Products, Optional Products will not fail the Link attempt if the necessary OAuth permissions are not granted. If the user does not grant access to the data needed to support an Optional Product in the OAuth linking flow, they will not be required to go through the OAuth flow again to update their permissions. Instead, the Item will be successfully created and the Optional Product will be unavailable until you have prompted the user to fix their permissions via [Update Mode](https://plaid.com/docs/link/update-mode/index.html.md) .

If Auth is specified in the Optional Products array, Auth will only be added to the Item if the institution supports [Instant Auth](https://plaid.com/docs/auth/coverage/instant/index.html.md) .

If you specify Auth, Identity, and/or Signal in the Optional Products array, you will only be billed for these products if you call their endpoints.

#### When to use Required if Supported Products 

If your only reason for omitting a product from the Products array is to increase the number of institutions covered, you should specify the product in the Required if Supported Products array rather than adding the product by calling its endpoint. Initializing both products during Link will make it easier to obtain the consent required at institutions that use OAuth, because the user will be prompted to fix their selections during the OAuth flow if they do not grant the required consent for all products. Initializing both products upfront can also reduce latency, because it allows Plaid to begin fetching data immediately and to optimize the order in which different types of data are requested.

For example, one common pattern for payments customers is to use Auth in the Products array, and Identity in the Required if Supported Products array. This means you will get Identity coverage for all accounts where it's available, but you won't block customers from linking their accounts if their institution doesn't support Identity.

Required if Supported Products is recommended over Optional Products if it is important to your use case that your user not be able to link an account if they've opted out of using certain products in the OAuth flow. For example, if you're accepting ACH payments, you might not want to let a user link their account while opting out of products used for risk mitigation, like Identity or Signal.

#### When to use Optional Products 

If you think that you may want to use Auth, Identity, and/or Signal for an Item, but it isn't necessary for all users, you should specify the product in the Optional Products array, because doing so will significantly reduce API latency when you call the product's endpoints later on.

As an example of when to use the Optional Products array, if your app primarily uses Transactions for budgeting but also uses Auth to transfer funds for a small percentage of users (e.g., paid users), you should specify Transactions in the Products array and Auth in the Optional Products array. This will ensure that all Items support Transactions, while also ensuring that Plaid will collect Auth data for as many users as possible without affecting Link conversion or increasing your Auth bill.

As an example of when _not_ to use the Optional Products array, if your app primarily uses Auth for funds transfers but also offers an optional budgeting add-on that uses Transactions, you should specify Auth in the Products array and Transactions in the Additional Consented Products array, and then add Transactions to the Item by calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) only once your user opts in to using the budgeting tool. This will prevent you from being billed for Transactions before you are sure you need to use it.

#### Special cases for Link initialization 

There are some exceptions to the ability to initialize consented products by calling their endpoints:

*   Bank Income and Assets can both be initialized post-Link, but may require re-launching Link to obtain additional consent. See [Verifying Bank Income for existing Items](https://plaid.com/docs/income/bank-income/index.html.md#verifying-bank-income-for-existing-items) and [Adding Assets to existing Items](https://plaid.com/docs/assets/index.html.md#getting-an-asset-report-for-an-existing-item) .
*   Identity Verification and Payment Initiation cannot be initialized post-Link.
*   When Auth is initialized post-Link, the main Instant Auth flow can be used, but the less common Instant Match, Automated Micro-deposits, or Same Day Micro-deposits flows cannot be initialized post-Link, as these are interactive flows that require user input.

Some products have limitations on being initialized alongside other products in the same Link session:

*   Plaid Check products (such as Consumer Report) cannot be initialized in the same Link session as Assets or Income Verification.
*   To use Same Day Micro-deposits, Database Insights, or Database Match, Auth must be the only product in the `products` array when initializing Link. However, you can add Signal or Identity to these Items via the `optional_products`, `required_if_supported_products`, or `additional_consented_products` fields.
*   If using Layer, the other products must be added via the `products` array; Layer sessions are not compatible with `optional_products`, `required_if_supported_products`, or `additional_consented_products`.
*   Income can only be initialized alongside other products if using Bank Income; Payroll Income and Document Income cannot be initialized alongside other products.
*   Identity Verification and Payment Initiation cannot be initialized alongside any other products. If you need to use these products along with other Plaid products, your user will need to launch the Link flow a second time.

#### Recommendations for initializing Link with specific product combinations 

##### Auth with Identity and/or Signal 

Initialize Link with Auth and Signal in the Products array and Identity in the Required if Supported Products array. Specifying Identity in the Required if Supported Products array will increase conversion while minimizing latency when calling Identity endpoints.

For most use cases, it is recommended to put Identity in Required if Supported Products instead of Optional Products. Using Optional Products for Identity allows customers at some OAuth institutions to opt out of sharing identity data and still complete the Link flow. Bad actors are likely to opt out of data sharing, reducing the usefulness of Identity as a fraud detection tool.

If you are willing to take on more risk, you can initialize with Identity in the Optional Products array instead, which will increase conversion and prevent you from being billed for Identity when you don't use it.

If you will only call Signal on some Items, not all, and if you are willing to proceed without Signal if it is not available, put Signal in the Optional Products array instead of the Products array.

If you initialize with Signal in the `additional_consented_products` array, you will need to call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) before calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) for the first time on an Item in order to get the most accurate results. For more details, see [Adding Signal to existing Items](https://plaid.com/docs/signal/creating-signal-items/index.html.md#adding-signal-to-existing-items) .

##### Auth with Assets 

Initialize Link with Assets in the Products array and Auth in the Required if Supported Products array. This will allow your user to link any account type, not just checking or savings accounts, which is important for getting their full financial picture.

##### Transactions with Auth and/or Identity 

If Transactions is the primary product, initialize with Transactions in the Products array, Auth in the Optional Products array, and Identity in the Required if Supported Products array. This will reduce latency when calling the Auth and/or Identity endpoints while maximizing institution coverage. It will also prevent you from being charged for Auth unless you end up calling its endpoints.

For most use cases, it is recommended to put Identity in Required if Supported Products instead of Optional Products. Using Optional Products for Identity allows customers at some OAuth institutions to opt out of sharing identity data and still complete the Link flow. Bad actors are likely to opt out of data sharing, reducing the usefulness of Identity as a fraud detection tool.

If you are willing to take on more risk, you can initialize with Identity in the Optional Products array instead, which will increase conversion and prevent you from being billed for Identity when you don't use it.

##### Transactions with Liabilities and/or Investments 

For personal finance use cases, initialize Link with Transactions, with Liabilities and Investments in the Additional Consented Products array. Then call Liabilities or Investments endpoints after the Item has been linked, based on the account type that was linked. Because virtually all Items that support Liabilities or Investments also support Transactions, this will maximize conversion. If you call an endpoint that is not applicable to the Item (for example, if you call [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) on a checking account, or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) on a credit card account), the call will fail and you will not be billed for it.

##### Bank Income with Transactions 

Initialize with Income Verification, add Transactions to Additional Consented Products, then call Transactions endpoints later, after the Item has been linked. Because Bank Income must fetch transaction data in order to verify the user's income, initializing with Transactions is not necessary. (Even though Bank Income uses transaction data, you will not be billed for Transactions on a Bank Income Item unless you add Transactions to the Item, either during or after Link.)

##### Bank Income with Assets 

Initialize Link with both Income Verification and Assets in the Products array. Because institutions that support one of these products almost always support both of them, and because you will not be billed for Assets until you call the Assets endpoints, this is safe to do even if you aren't sure if you will use Assets. Assets can't be added to an Item post-Link without sending the user through Update Mode, so including Assets upfront will increase conversion.

If you already have an Item enabled with one of these products and want to add the other: see the instructions on [Verifying Bank Income for existing Items](https://plaid.com/docs/income/bank-income/index.html.md#verifying-bank-income-for-existing-items) to add Bank Income to the Item. See the instructions on [Getting an Asset Report for an existing Item](https://plaid.com/docs/assets/index.html.md#getting-an-asset-report-for-an-existing-item) to add Assets.

---


# Link - Institution status in Link | Plaid Docs

Institution status in Link 
===========================

#### Details of institution health status accessible in Link 

#### Institution status in Link 

Link proactively lets users know if an institution's connection isn't performing well. Below are the three views a user will see depending on the status of the institution they select.

When the status of `item_logins` of an institution is `DEGRADED`, Link will warn users that they may experience issues and allow them to continue. Once the status of `item_logins` becomes `DOWN`, Link will block users from attempting to log in and suggest they find another bank.

(An image of "Plaid Link institution status panels: Healthy allows credential input; Degraded shows connectivity issue; Down indicates connection failure.")

Institution Health warnings can be tested in the Sandbox environment by using one of the dedicated ["Unhealthy" Platypus Bank test institutions](https://plaid.com/docs/sandbox/institutions/index.html.md#institution-details) .

For a more detailed view of institution status, see the [status dashboard](https://dashboard.plaid.com/activity/status) , which provides a browsable view of institutions, supported products, and institution health.

#### Connectivity not supported 

(An image of "Plaid Link message: 'Connectivity not supported' for simple institution. Advises trying another institution.")

If an institution is supported by Plaid, but is not supported by the product set or country codes Link was initialized with, a "Connectivity not supported" error message will appear. This message does not reflect the health of the institution. This message can be resolved by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with a more minimal product set, or by making sure you are Production-enabled for the country you are initializing Link for. For more details, see [Link troubleshooting](https://plaid.com/docs/link/troubleshooting/index.html.md#missing-institutions-or-connectivity-not-supported-error) .

---


# Link - iOS | Plaid Docs

Link iOS SDK 
=============

#### Reference for integrating with the Link iOS SDK 

#### Overview 

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your iOS app. LinkKit is a drop-in framework that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.) without passing sensitive information to your server.

[Prefer to learn by watching? Check out this quick guide to implementing Plaid on iOS devices](https://www.youtube.com/watch?v=QXHHRSSaspY)

Want even more video lessons? A [full tutorial](https://youtu.be/9fgmW38usTo) for integrating Plaid with iOS is available on our YouTube channel.

To get started with Plaid Link for iOS, clone the [GitHub repository](https://github.com/plaid/plaid-link-ios) and try out the example application, which provides a reference implementation in both Swift and Objective-C. Youʼll want to sign up for [free API keys](https://dashboard.plaid.com/developers/keys) through the Plaid Dashboard to get started.

(An image of "Plaid Link iOS example: Credentials entry, account selection, and successful connection confirmation screens.")

#### Initial iOS setup 

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

The "Register your redirect URI" and "Set up Universal Links" steps describe setting up your app for OAuth redirects. If your integration uses only Identity Verification, Monitor, Beacon, or Document Income, they can be skipped; they are mandatory otherwise.

##### Register your redirect URI 

1.  Sign in to the [Plaid Dashboard](https://dashboard.plaid.com/signin) and go to the [Team Settings -> API](https://dashboard.plaid.com/developers/api) page.
2.  Next to **Allowed redirect URIs** click **Configure** then **Add New URI**.
3.  Enter your redirect URI, which you must also set up as a Universal Link for your application, for example: `https://app.example.com/plaid/`.
4.  Click **Save Changes**.

These redirect URIs must be set up as [Universal Links](https://developer.apple.com/ios/universal-links/) in your application. For details, see Apple's documentation on [Allowing Apps and Websites to Link to Your Content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) .

Plaid does not support registering URLs with custom URL schemes as redirect URIs since they lack the security of Universal Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete Plaid OAuth flows, it is important that _your_ application is opened and not any arbitrary application that has registered the same URL scheme.

##### Set up Universal Links 

In order for Plaid to return control back to your application after a user completes a bank's OAuth flow, you must specify a redirect URI, which will be the URI from which Link will be re-launched to complete the OAuth flow. The redirect URI must be a Universal Link. An example of a typical redirect URI is: `https://app.example.com/plaid`.

Universal Links consist of the following parts:

*   An `applinks` entitlement for the Associated Domains capability in your app. For details, see Apple’s documentation on the [Associated Domains Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains) and the [entitlements example](https://github.com/plaid/plaid-link-ios/blob/master/LinkDemo-Swift/LinkDemo-Swift/LinkDemo-Swift.entitlements) in the LinkDemo-Swift example app.
*   An `apple-app-site-association` file on your website. For details, see Apple’s documentation on [Supporting Associated Domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) and see our minimal example below.

There are a few requirements for `apple-app-site-association` files:

*   Must be a static JSON file
*   Must be hosted using a `https://` scheme with a valid certificate and no redirects
*   Must be hosted at `https://<my-fully-qualified-domain>/.well-known/apple-app-site-association`

Below is an example for `https://my-app.com` (`https://my-app.com/.well-known/apple-app-site-association`)

```json
{
  "applinks": {
    "details": [
      {
        "appIDs": ["."],
        "components": [
          {
            "/": "/plaid/*",
            "comment": "Matches any URL path whose path starts with /plaid/"
          }
        ]
      }
    ]
  }
}
```

Once you have enabled Universal Links, your iOS app is now set up and ready to start integrating with the Plaid SDK.

Ensure that the corresponding entry for the configured redirect URI in the `apple-app-site-association` file on your website continues to be available. If it is removed, OAuth sessions will fail until it is available again.

#### Installation 

Plaid Link for iOS is an embeddable framework that is bundled and distributed with your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using [Swift Package Manager](https://swiftpackageindex.com/plaid/plaid-link-ios) or [CocoaPods](https://cocoapods.org/pods/Plaid) . Regardless of what you choose, submitting a new version of your application with the updated [LinkKit.xcframework](https://github.com/plaid/plaid-link-ios/releases) to the App Store is required.

##### Requirements 

| LinkKit iOS version | Xcode toolchain minimum support | Supported iOS versions |
| --- | --- | --- |
| LinkKit 5.x.x | Xcode 15 | iOS 14 or greater |
| LinkKit 4.x.x | Xcode 14 | iOS 11 or greater |
| LinkKit 3.x.x | Xcode 13 | iOS 11 or greater |

Select group for content switcher

Swift Package ManagerCocoaPodsManual

##### Swift Package Manager 

1.  To integrate LinkKit using Swift Package Manager, Swift version >= 5.3 is required.
2.  In your Xcode project from the Project Navigator (**Xcode ❯ View ❯ Navigators ❯ Project ⌘ 1**) select your project, activate the **Package Dependencies** tab and click on the plus symbol **➕** to open the **Add Package** popup window:
    
    (An image of "Xcode interface showing how to add a Swift package dependency; plus button highlighted.")
    
3.  Enter the LinkKit package URL `https://github.com/plaid/plaid-link-ios-spm` into the search bar in the top right corner of the **Add Package** popup window. The main repository with full git history is very large (~1 GB), and Swift Package Manager always downloads the full repository with all git history. This `plaid-link-ios-spm` repository is much smaller (less than 500kb), making the download faster.
4.  Select the `plaid-link-ios-spm` package.
5.  Choose your **Dependency Rule** (we recommend **Up to Next Major Version**).
6.  Select the project to which you would like to add LinkKit, then click **Add Package**:
    
    (An image of "Xcode screenshot showing input of Plaid Link iOS Swift package URL for package addition. 'Add Package' button highlighted.")
    
7.  Select the `LinkKit` package product and click **Add Package**:
    
    (An image of "Dialog in Xcode for selecting Plaid link-ios package. 'LinkKit' checked, type 'Library', target 'MySampleApp'.")
    
8.  Verify that the LinkKit Swift package was properly added as a package dependency to your project:
    
    (An image of "Xcode showing the Plaid Link iOS package dependency from GitHub in Package Dependencies tab.")
    
9.  Select your application target and ensure that the LinkKit library is embedded into your application:
    
    (An image of "Xcode screenshot showing the Frameworks section with LinkKit listed under Package Dependencies for MySampleApp.")
    

##### CocoaPods 

1.  If you haven’t already, install the latest version of [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) .
2.  If you don’t have an existing Podfile, run the following command to create one:
    
    ```bash
    pod init
    ```
    
3.  Add this line to your `Podfile`:
    
    ```bash
    pod 'Plaid'
    ```
    
4.  Run the following command:
    
    ```bash
    pod install
    ```
    
5.  To update to newer releases in the future, run:
    
    ```bash
    pod install
    ```
    

##### Manual 

Get the latest version of the [LinkKit.xcframework](https://github.com/plaid/plaid-link-ios/releases) and embed it into your application, for example by dragging and dropping the XCFramework bundle onto the **Embed Frameworks** build phase of your application target in Xcode as shown below.

(An image of "Xcode project with LinkKit.xcframework added under Frameworks, Libraries, and Embedded Content. LinkKit.xcframework folder in Downloads.")

  

##### Camera Support (Identity Verification only) 

When using the [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) product, the Link SDK may use the camera if a user needs to take a picture of identity documentation. To support this workflow, add a [NSCameraUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nscamerausagedescription) entry to your application's plist with an informative string. This allows iOS to prompt the user for camera access. iOS will crash your application if this string is not provided.

##### Upgrading 

New versions of [LinkKit.xcframework](https://github.com/plaid/plaid-link-ios/releases) are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application.

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

For details on each release see the [GitHub releases](https://github.com/plaid/plaid-link-ios/releases) and [version release notes](https://github.com/plaid/plaid-link-ios/blob/master/CHANGELOG.md) .

\=\*=\*=\*=

#### Opening Link 

Before you can open Link, you need to first create a `link_token`. A `link_token` can be configured for different Link flows and is used to control much of Link’s behavior. To learn how to create a new `link_token`, see the API Reference entry for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

For iOS the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call must include the `redirect_uri` parameter and it must match the redirect URI you have configured with Plaid (see [Register your redirect URI](https://plaid.com/docs/link/ios/index.html.md#register-your-redirect-uri) above).

##### Create a Configuration 

Starting the Plaid Link for iOS experience begins with creating a `link_token`. Once the `link_token` is passed to your app, create an instance of `LinkTokenConfiguration`, then create a `Handler` using `Plaid.create()` passing the previously created `LinkTokenConfiguration`. Plaid will begin to pre-load Link as soon as `Plaid.create()` is called, so to reduce UI latency when rendering Link, you should call `Plaid.create()` when initializing the screen where the user can enter the Link flow.  
After calling `Plaid.create()`, to show the Link UI, call `open()` on the handler passing your preferred presentation method.  
Note that each time you open Link, you will need to get a new `link_token` from your server and create a new `LinkTokenConfiguration` with it.

**Properties**

[token](https://plaid.com/docs/link/ios/index.html.md#link-ios-create-token)

String

Specify a `link_token` to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for more details.

[onSuccess](https://plaid.com/docs/link/ios/index.html.md#link-ios-create-onSuccess)

closure

A required closure that is called when a user successfully links an Item. The closure should expect a single `LinkSuccess` argument, containing the `publicToken` String and a `metadata` of type `SuccessMetadata`. See [onSuccess](https://plaid.com#onsuccess) below.

[onExit](https://plaid.com/docs/link/ios/index.html.md#link-ios-create-onExit)

closure

An optional closure that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The closure should expect a single `LinkExit` argument, containing an optional `error` and a `metadata` of type `ExitMetadata`. See [onExit](https://plaid.com#onexit) below.

[onEvent](https://plaid.com/docs/link/ios/index.html.md#link-ios-create-onEvent)

closure

An optional closure that is called when a user reaches certain points in the Link flow. The closure should expect a single `LinkEvent` argument, containing an `eventName` enum of type `EventType` and a `metadata` of type `EventMetadata`. See [onEvent](https://plaid.com#onevent) below.

```clike
var linkConfiguration = LinkTokenConfiguration(
    token: "<#LINK_TOKEN_FROM_SERVER#>",
    onSuccess: { linkSuccess in
        // Send the linkSuccess.publicToken to your app server.
    }
)


// Optional: Configure additional Link presentation options. 


// If true, skips the default Link loading animation.
// Use this if you're displaying your own custom loading UI.
linkConfiguration.noLoadingState = true


// Optional: Configure additional Link presentation options -
// Available in SDK v6.2.0 and above:


// If false, displays a solid background instead of the default
// transparent gradient.
linkConfiguration.showGradientBackground = false
```

##### Create a Handler 

A `Handler` is a one-time use object used to open a Link session. The `Handler` must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link redirects. For more details, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md#ios) .

You can optionally provide an `onLoad` (available in **SDK v6.2.0 and above**) callback to know when Link has finished preloading and is ready to be presented. This is useful if you want to delay presenting Link until it’s fully loaded, or enable related UI elements.

Note for Layer customers: You should wait for the `LAYER_READY` event before presenting Link, rather than relying solely on `onLoad`.

```clike
let result = Plaid.create(configuration, onLoad: { [weak self] in
    // Optional callback that is invoked once Plaid Link has
    // finished loading and is ready to be presented.
    // You could use your own loading UI and automatically
    // launch Link when this callback fires.
    //
    // Ex:
    //    guard let self = self else { return }
    //    self.handler?.open(presentUsing: .viewController(self))
    //


    // Ex: Enable a button once Link has loaded
    //    self?.openButton.isEnabled = true
})


switch result {
case .failure(let error):
    logger.error("Unable to create Plaid handler due to: \(error)")
case .success(let handler):
    self.handler = handler
}
```

##### Open Link 

Finally, open Link by calling `open` on the `Handler` object. This will usually be done in a button’s target action.

```clike
let method: PresentationMethod = .viewController(self)
handler.open(presentUsing: method)
```

\=\*=\*=\*=

#### onSuccess 

The closure is called when a user successfully links an Item. It should take a single `LinkSuccess` argument, containing the `publicToken` String and a `metadata` of type `SuccessMetadata`.

**Properties**

[linkSuccess](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess)

LinkSuccess

Contains the `publicToken` and `metadata` for this successful flow.

[publicToken](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-publicToken)

String

Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used.

[metadata](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata)

LinkSuccess

Displayed once a user has successfully completed Link.

[institution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-institution)

nullable, Institution

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-institution-name)

String

The full institution name, such as 'Wells Fargo'

[institutionID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-institution-institutionID)

InstitutionID (String)

The Plaid institution identifier

[accounts](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts)

Array<Account>

A list of accounts attached to the connected Item

[id](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts-id)

AccountID (String)

The Plaid `account_id`

[name](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts-name)

String

The official account name

[mask](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts-mask)

Optional<AccountMask> (Optional<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.

[subtype](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts-subtype)

AccountSubtype

The account subtype and its type. See [Account Types](https://plaid.com/docs/api/accounts/index.html.md#accounts-schema) for a full list of possible values.

[verificationStatus](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts-verificationStatus)

Optional<VerificationStatus>

Indicates an Item's micro-deposit-based verification or database verification status. 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 deposit.  
`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.  
`database_matched`: The Item has successfully been verified using Plaid's data sources.  
`database_insights_pending`: The Database Insights result is pending and will be available upon Auth request.  
`nil`: Neither micro-deposit-based verification nor database verification are being used for the Item.

[linkSessionID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-linkSessionID)

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.

[metadataJSON](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-metadataJSON)

String

Unprocessed metadata, formatted as JSON, sent from the Plaid API.

```clike
onSuccess: { linkSuccess in
  // Send the linkSuccess.publicToken to your app server.
}
```

\=\*=\*=\*=

#### onExit 

This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single `LinkExit` argument, containing an optional `error` and a `metadata` of type `ExitMetadata`.

**Properties**

[linkExit](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit)

LinkExit

Contains the optional `error` and `metadata` for when the flow was exited.

[error](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-error)

Optional<ExitError> (Swift), Optional<NSError> (Objective-C)

An Error type that contains the `errorCode`, `errorMessage`, and `displayMessage` of the error that was last encountered by the user. If no error was encountered, `error` will be `nil`. In Objective-C, field names will match the `NSError` type.

[errorCode](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-error-errorCode)

ExitErrorCode

The error code and error type that the user encountered. Each `errorCode` has an associated `errorType`, which is a broad categorization of the error.

[errorMessage](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-error-errorMessage)

String

A developer-friendly representation of the error code.

[displayMessage](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-error-displayMessage)

Optional<String>

A user-friendly representation of the error code or `nil` if the error is not related to user action. This may change over time and is not safe for programmatic use.

[metadata](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata)

ExitMetadata

Displayed if a user exits Link without successfully linking an Item.

[status](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status)

Optional<ExitStatus>

The status key indicates the point at which the user exited the Link flow.

[requiresQuestions](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-requiresQuestions)

User prompted to answer security question(s).

[requiresSelections](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-requiresSelections)

User prompted to answer multiple choice question(s).

[requiresCode](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-requiresCode)

User prompted to provide a one-time passcode.

[chooseDevice](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-chooseDevice)

User prompted to select a device on which to receive a one-time passcode.

[requiresCredentials](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-requiresCredentials)

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.

[requiresAccountSelection](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-requiresAccountSelection)

User prompted to select one or more financial accounts to share

[institutionNotFound](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-institutionNotFound)

User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.

[institutionNotSupported](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-institutionNotSupported)

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

[unknown](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-status-unknown)

The exit status has not been defined in the current version of the SDK. The `unknown` case has an associated value carrying the original exit status as sent by the Plaid API.

[institution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-institution)

Optional<Institution>

An institution object. If the Item was created via Same-Day micro-deposit verification, will be omitted.

[institutionID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-institution-institutionID)

InstitutionID (String)

The Plaid specific identifier for the institution.

[name](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-institution-name)

String

The full institution name, such as 'Wells Fargo'.

[linkSessionID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-linkSessionID)

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

[requestID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-requestID)

Optional<String>

The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.

[metadataJSON](https://plaid.com/docs/link/ios/index.html.md#link-ios-onexit-linkExit-metadata-metadataJSON)

RawJSONMetadata (String)

Unprocessed metadata, formatted as JSON, sent from Plaid API.

```clike
linkConfiguration.onExit = { linkExit in
  // Optionally handle linkExit data according to your application's needs
}
```

\=\*=\*=\*=

#### onEvent 

This closure is called when certain events in the Plaid Link flow have occurred. The `open`, `layerReady`, and `layerNotAvailable` events are guaranteed to fire in real time; other events will typically be fired when the Link session finishes, when `onSuccess` or `onExit` is called. Callback ordering is not guaranteed; `onEvent` callbacks may fire before, after, or surrounding the `onSuccess` or `onExit` callback, and event callbacks are not guaranteed to fire in the order in which they occurred.  
The following `onEvent` callbacks are stable, which means that they are suitable for programmatic use in your application's logic: `open`, `exit`, `handoff`, `selectInstitution`, `error`, `bankIncomeInsightsCompleted`, `identityVerificationPassSession`, `identityVerificationFailSession`, `layerReady`, `layerNotAvailable`. The remaining callback events are informational and subject to change, and should be used for analytics and troubleshooting purposes only.

**Properties**

[linkEvent](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent)

LinkEvent

Contains the `eventName` and `metadata` for the Link event.

[eventName](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName)

EventName

An enum representing the event that has just occurred in the Link flow.

[autoSubmitPhone](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-autoSubmitPhone)

The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid.

[bankIncomeInsightsCompleted](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-bankIncomeInsightsCompleted)

The user has completed the Assets and Bank Income Insights flow.

[closeOAuth](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-closeOAuth)

The user closed the third-party website or mobile app without completing the OAuth flow.

[connectNewInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-connectNewInstitution)

The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Remember Me flow.

[error](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-error)

A recoverable error occurred in the Link flow, see the `errorCode` in the metadata.

[exit](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-exit)

The user has exited without completing the Link flow and the [onExit](https://plaid.com#onexit) callback is fired.

[failOAuth](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-failOAuth)

The user encountered an error while completing the third-party's OAuth login flow.

[handoff](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-handoff)

The user has exited Link after successfully linking an Item.

[identityMatchFailed](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityMatchFailed)

An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match.

[identityMatchPassed](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityMatchPassed)

An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match.

[identityVerificationStartStep](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationStartStep)

The user has started a step of the Identity Verification flow. The step is indicated by `view_name`.

[identityVerificationPassStep](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationPassStep)

The user has passed a step of the Identity Verification flow. The step is indicated by `view_name`.

[identityVerificationFailStep](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationFailStep)

The user has failed a step of the Identity Verification flow. The step is indicated by `view_name`.

[identityVerificationPendingReviewStep](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationPendingReviewStep)

The user has reached the pending review state.

[identityVerificationCreateSession](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationCreateSession)

The user has started a new Identity Verification session.

[identityVerificationResumeSession](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationResumeSession)

The user has resumed an existing Identity Verification session.

[identityVerificationPassSession](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationPassSession)

The user has passed their Identity Verification session.

[identityVerificationFailSession](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationFailSession)

The user has failed their Identity Verification session.

[identityVerificationPendingReviewSession](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationPendingReviewSession)

The user has completed their Identity Verification session, which is now in a pending review state.

[identityVerificationOpenUI](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationOpenUI)

The user has opened the UI of their Identity Verification session.

[identityVerificationResumeUI](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationResumeUI)

The user has resumed the UI of their Identity Verification session.

[identityVerificationCloseUI](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-identityVerificationCloseUI)

The user has closed the UI of their Identity Verification session.

[layerAutofillNotAvailable](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-layerAutofillNotAvailable)

The user's date of birth passed to Link is not eligible for Layer autofill.

[layerNotAvailable](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-layerNotAvailable)

The user phone number passed to Link is not eligible for Layer.

[layerReady](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-layerReady)

The user phone number passed to Link is eligible for Layer and `open()` may now be called.

[matchedSelectInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-matchedSelectInstitution)

The user selected an institution that was presented as a matched institution. This event can be emitted if [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) is being used, if the institution was surfaced as a matched institution likely to have been linked to Plaid by a returning user, or if the institution's `routing_number` was provided when calling `/link/token/create`. For details on which scenario is triggering the event, see `metadata.matchReason`.

[open](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-open)

The user has opened Link.

[openMyPlaid](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-openMyPlaid)

The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.

[openOAuth](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-openOAuth)

The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.

[searchInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-searchInstitution)

The user has searched for an institution.

[selectAuthType](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-selectAuthType)

The user has chosen whether to Link instantly or manually (i.e., with micro-deposits). This event emits the `selection` metadata to indicate the user's selection.

[selectBrand](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-selectBrand)

The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

[selectDegradedInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-selectDegradedInstitution)

The user selected an institution with a `DEGRADED` health status and was shown a corresponding message.

[selectDownInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-selectDownInstitution)

The user selected an institution with a `DOWN` health status and was shown a corresponding message.

[selectFilteredInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-selectFilteredInstitution)

The user selected an institution Plaid does not support all requested products for and was shown a corresponding message.

[selectInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-selectInstitution)

The user selected an institution.

[skipSubmitPhone](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-skipSubmitPhone)

The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Remember Me flow.

[submitAccountNumber](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitAccountNumber)

The user has submitted an account number. This event emits the `accountNumberMask` metadata to indicate the mask of the account number the user provided.

[submitCredentials](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitCredentials)

The user has submitted credentials.

[submitDocuments](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitDocuments)

The user is being prompted to submit documents for an Income verification flow.

[submitDocumentsError](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitDocumentsError)

The user encountered an error when submitting documents for an Income verification flow.

[submitDocumentsSuccess](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitDocumentsSuccess)

The user has successfully submitted documents for an Income verification flow.

[submitMFA](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitMFA)

The user has submitted MFA.

[submitOTP](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitOTP)

The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience flow.

[submitPhone](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitPhone)

The user has submitted their phone number. This event is only emitted in the Link Remember Me flow.

[submitRoutingNumber](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-submitRoutingNumber)

The user has submitted a routing number. This event emits the `routingNumber` metadata to indicate user's routing number.

[transitionView](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-transitionView)

The `transitionView` event indicates that the user has moved from one view to the next.

[uploadDocuments](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-uploadDocuments)

The user is asked to upload documents (for Income verification).

[verifyPhone](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-verifyPhone)

The user has successfully verified their phone number. This event is only emitted in the Link Remember Me flow.

[viewDataTypes](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-viewDataTypes)

The user has viewed data types on the data transparency consent pane.

[unknown](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-eventName-unknown)

The event has not been defined in the current version of the SDK. The `unknown` case has an associated value carrying the original event name as sent by the Plaid API.

[metadata](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata)

EventMetadata struct

An object containing information about the event

[accountNumberMask](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-accountNumberMask)

Optional<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`.

[errorCode](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-errorCode)

Optional<ExitErrorCode>

The error code that the user encountered. Emitted by: `error`, `exit`.

[errorMessage](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-errorMessage)

Optional<String>

The error message that the user encountered. Emitted by: `error`, `exit`.

[exitStatus](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus)

Optional<ExitStatus>

The status key indicates the point at which the user exited the Link flow. Emitted by: `exit`.

[requiresQuestions](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-requiresQuestions)

User prompted to answer security question(s).

[requiresSelections](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-requiresSelections)

User prompted to answer multiple choice question(s).

[requiresCode](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-requiresCode)

User prompted to provide a one-time passcode.

[chooseDevice](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-chooseDevice)

User prompted to select a device on which to receive a one-time passcode.

[requiresCredentials](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-requiresCredentials)

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.

[institutionNotFound](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-institutionNotFound)

User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.

[unknown](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-exitStatus-unknown)

The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.

[institutionID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-institutionID)

Optional<InstitutionID> (Optional<String>)

The ID of the selected institution. Emitted by: _all events_.

[institutionName](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-institutionName)

Optional<String>

The name of the selected institution. Emitted by: _all events_.

[institutionSearchQuery](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-institutionSearchQuery)

Optional<String>

The query used to search for institutions. Emitted by: `searchInstitution`.

[isUpdateMode](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-isUpdateMode)

Optional<String>

Indicates if the current Link session is an update mode session. Emitted by: `OPEN`.

[matchReason](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-matchReason)

nullable, 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`.

[linkSessionID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-linkSessionID)

String

The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_.

[mfaType](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-mfaType)

Optional<MFAType>

If set, the user has encountered one of the following MFA types: `code`, `device`, `questions`, `selections`. Emitted by: `submitMFA` and `transitionView` when `viewName` is `mfa`

[requestID](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-requestID)

Optional<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_.

[routingNumber](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-routingNumber)

Optional<String>

The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`.

[selection](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-selection)

Optional<String>

The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`.

[timestamp](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-timestamp)

Date

An ISO 8601 representation of when the event occurred. For example `2017-09-14T14:42:19.350Z`. Emitted by: _all events_.

[viewName](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName)

Optional<ViewName>

The name of the view that is being transitioned to. Emitted by: `transitionView`.

[acceptTOS](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-acceptTOS)

The view showing Terms of Service in the identity verification flow.

[connected](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-connected)

The user has connected their account.

[consent](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-consent)

We ask the user to consent to the privacy policy.

[credential](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-credential)

Asking the user for their account credentials.

[documentaryVerification](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-documentaryVerification)

The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).

[error](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-error)

An error has occurred.

[exit](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-exit)

Confirming if the user wishes to close Link.

[instantMicrodepositAuthorized](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-instantMicrodepositAuthorized)

The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.

[kycCheck](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-kycCheck)

The view representing the "know your customer" step in the identity verification flow.

[loading](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-loading)

Link is making a request to our servers.

[mfa](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-mfa)

The user is asked by the institution for additional MFA authentication.

[numbers](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-numbers)

The user is asked to insert their account and routing numbers.

[numbersSelectInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-numbersSelectInstitution)

The user goes through the Same Day micro-deposits flow with Reroute to Credentials.

[oauth](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-oauth)

The user is informed they will authenticate with the financial institution via OAuth.

[profileDataReview](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-profileDataReview)

The user is asked to review their profile data in the Layer flow.

[recaptcha](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-recaptcha)

The user was presented with a Google reCAPTCHA to verify they are human.

[riskCheck](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-riskCheck)

The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).

[sameDayMicrodepositAuthorized](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-sameDayMicrodepositAuthorized)

The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.

[screening](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-screening)

The watchlist screening step in the identity verification flow.

[selectAccount](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selectAccount)

We ask the user to choose an account.

[selectAuthType](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selectAuthType)

The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).

[selectBrand](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selectBrand)

The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

[selectInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selectInstitution)

We ask the user to choose their institution.

[selectSavedAccount](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selectSavedAccount)

The user is asked to select their saved accounts and/or new accounts for linking in the Link Remember Me flow.

[selectSavedInstitution](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selectSavedInstitution)

The user is asked to pick a saved institution or link a new one in the Link Remember Me flow.

[selfieCheck](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-selfieCheck)

The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.

[submitPhone](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-submitPhone)

The user is asked for their phone number in the Link Remember Me flow.

[uploadDocuments](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-uploadDocuments)

The user is asked to upload documents (for Income verification).

[verifyPhone](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-verifyPhone)

The user is asked to verify their phone OTP in the Link Remember Me flow.

[verifySMS](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-verifySMS)

The SMS verification step in the identity verification flow.

[unknown](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-viewName-unknown)

The view has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original view name as sent by the Plaid API.

[metadataJSON](https://plaid.com/docs/link/ios/index.html.md#link-ios-onevent-linkEvent-metadata-metadataJSON)

RawJSONMetadata (String)

Unprocessed metadata, formatted as JSON, sent from Plaid API.

```clike
linkConfiguration.onEvent = { linkEvent in
  // Optionally handle linkEvent data according to your application's needs
}
```

\=\*=\*=\*=

#### Submit 

The `submit` function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number).

**Properties**

[submissionData](https://plaid.com/docs/link/ios/index.html.md#link-ios-submit-submissionData)

object

Data to submit during a Link session.

[phoneNumber](https://plaid.com/docs/link/ios/index.html.md#link-ios-submit-submissionData-phoneNumber)

String

The end user's phone number.

[dateOfBirth](https://plaid.com/docs/link/ios/index.html.md#link-ios-submit-submissionData-dateOfBirth)

String

The end user's date of birth. To be provided in the format "yyyy-mm-dd".

```clike
// Create a model that conforms to the SubmissionData interface
struct PlaidSubmitData: SubmissionData {
    var phoneNumber: String?
}


let data = PlaidSubmitData(phoneNumber: "14155550015")


self.handler.submit(data)
```

\=\*=\*=\*=

#### Next steps 

Once you've gotten Link working, see [Link best practices](https://plaid.com/docs/link/best-practices/index.html.md) for recommendations on further improving the Link flow.

---


# Link - Link Recovery (beta) | Plaid Docs

Link Recovery (beta) 
=====================

#### Notify users impacted by institution downtime to return to your app and link their accounts 

#### Overview 

Link Recovery (beta) allows you to provide a superior user experience and improved conversion when users run into issues connecting with an institution. When a user attempts to connect an institution that is experiencing a temporary connectivity outage, Link Recovery lets the user opt in to receiving an email notification from Plaid letting them know when the issue has been resolved. The user can then launch Link directly from a link in the email notification and complete the process of connecting their account.

Link Recovery is designed to be easy to implement and can be added to an existing Plaid integration with only a few lines of code.

The user encounters an error because their institution is down.

(An image of "The user encounters an error because their institution is down.")

(An image of "They elect to be notified when the problem is resolved.")

(An image of "They exit Link...")

(An image of "...and receive a confirmation email.")

(An image of "When the institution is back up, they are notified...")

(An image of "...and can click a link in the email to go directly to Link.")

(An image of "They connect to the institution...")

(An image of "...select their account...")

(An image of "...and receive a success screen with a button to redirect them to your app.")

Link Recovery is currently in beta. To request access, [complete this short Google form](https://docs.google.com/forms/d/e/1FAIpQLSfk98Di4SajVIG0xw5gLhEAKyspNBl8fvUrg32QJ7WnIvb9Cw/viewform) .

#### Integration steps 

##### Calling /link/token/create 

When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , specify the following, in addition to your normal parameters:

*   A `webhook` URI, where you will receive the `SESSION_FINISHED` webhook used to deliver the `public_token` for Link Recovery sessions.
*   (Optional) A `hosted_link.completion_redirect_uri`, indicating the URI that the user should be redirected to after completing a Link Recovery session. This field is optional, but strongly recommended; you can use it to redirect the user to your app so they can see the impact of linking their account.
*   If you are not specifying a `hosted_link.completion_redirect_uri`, include a `hosted_link` object (an empty object is fine) in the request in order to enable Hosted Link for your session. Link Recovery requires Hosted Link.

##### Listening for the SESSION\_FINISHED webhook 

Next, make sure to listen for the `SESSION_FINISHED` webhook, which will fire when your end user completes their Link Recovery session.

```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"
}
```

After retrieving the public token from the `public_tokens` array, you can exchange it as normal.

#### Testing Link Recovery 

Plaid will not send email notifications in the Sandbox environment, so the Link Recovery flow cannot be tested end-to-end in Sandbox. Instead, you can test the two parts of the flow separately.

To test that you are enabled for Link Recovery and that users can sign up to receive emails, log in to Link in Sandbox with the following credentials to simulate a temporary institution outage: username: `user_good` password: `error_INSTITUTION_DOWN`. (If you are not yet enabled for Link Recovery, you can also use the following credentials to see the Link Recovery experience in Sandbox: username: `user_link_recovery` password: `{}`.)

To test that the Link Recovery session works correctly, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and manually go to the `hosted_link_uri` present in the response. This will launch a Hosted Link session, where you can test going through the Link flow with the `user_good` / `pass_good` credentials and triggering the `SESSION_FINISHED` webhook.

---


# Link - Link Token migration guide | Plaid Docs

Link token migration guide 
===========================

#### How to migrate your application from the public key to a Link token 

Support for the public-key based integration mode will end on January 31, 2025. All customers still using the public key-based method of integration must switch to using Link tokens by this date, as public keys will no longer work to launch Link sessions beginning in February 2025.

Introduction 
-------------

Plaid has introduced a new `link_token`, which replaces the static `public_key`. This is an improvement that provides better error validation, more advanced security, and enables Link event logs to be surfaced in the Plaid Dashboard. While Plaid does not plan to discontinue support for existing `public_key` integrations, it is recommended that you upgrade your integration to use a `link_token`, as it enables enhanced capabilities, and future Plaid development and features will be based on the `link_token` infrastructure. Link tokens are also required for new OAuth integrations.

If you are unable to migrate to Link tokens at this time, see [maintaining a public key integration](https://plaid.com/docs/link/maintain-legacy-integration/index.html.md) for instructions on working with legacy public keys.

This guide covers the client and server-side changes required to implement the new `link_token`. Here's an overview of the updates before we dive into the details.

**The Plaid flow** begins when your user wants to connect their bank account to your app.

(An image of "Step diagram")

**1**Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to create a `link_token` and pass the temporary token to your app's client.

(An image of "Step 1 diagram")

**2**Use the `link_token` to open Link for your user. In the [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) , Link will provide a temporary `public_token`. This token can also be obtained on the backend via \`/link/token/get\`.

(An image of "Step 2 diagram")

**3**Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for a permanent `access_token` and `item_id` for the new `Item`.

(An image of "Step 3 diagram")

**4**Store the `access_token` and use it to make product requests for your user's `Item`.

(An image of "Step 4 diagram")

#### What's new 

*   Link will now be initialized with a new `link_token`. The `link_token` replaces all previous methods of initializing Link, including the `public_key` (for initial Link), the `public_token` (for update mode), and the `payment_token` (for Payment Initiation).
*   The new endpoint to create the `link_token` is [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   The [INVALID\_LINK\_TOKEN](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_link_token) error code is now available to gracefully handle invalidated tokens.
*   Link events from sessions created with the new `link_token` will be surfaced in the [Logs](https://dashboard.plaid.com/activity/logs) section of the Dashboard. However, Link events from sessions created with the `public_key` will not.

#### Link tokens 

The `link_token` is a new type of token that is created by your app's server and passed to your app's client to initialize Link. The Link configuration parameters that were previously set within Link itself are now set via parameters passed to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and conveyed to Link via the `link_token`. If these configurations are still set client-side when using the `link_token`, they will not have any effect on Link behavior.

Update your integration 
------------------------

The overall process for updating your integration is:

1.  Update your server to create a `link_token`.
2.  Update your client to pass the `link_token` and handle `INVALID_LINK_TOKEN` errors.
3.  Ensure you have updated all Link entry points, including those for update mode.
4.  Test your integration.
5.  Update any callsites that use the `public_key` for authentication to use the `client_id` and `secret` instead, then re-test those callsites.
6.  Disable the `public_key`.

Detailed instructions for each step can be found below.

#### Update your server 

Add a new authenticated endpoint to your app's server to create a `link_token` by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['transactions'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

Many of the parameters to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) are the same as parameters previously set in Link. Aside from the change to snake case from camelCase, there are a few substantive differences, summarized below. Note that these bullets are only a summary; for the full [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint definition, see the [API Reference](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

*   A new required parameter, `user.id`, has been added. This should be a unique identifier, such as the user ID of the end user in your application. It should not contain personally identifiable information, such as a phone number or email address.
*   `language` and `country_codes`, which were previously optional, are now required.
*   `accountSubtypes` has been replaced by the `account_filters` parameter, and its syntax has changed.

In addition, there are a few differences relevant specifically to European integrations:

*   The `oauthNonce` parameter is no longer used, since it is effectively replaced by `user.id`.
*   For the Payment Initiation product, The `paymentToken` is no longer used, and [/payment\_initiation/payment/token/create](https://plaid.com/docs/link/maintain-legacy-integration/index.html.md#creating-a-payment-token) has been deprecated. Instead, the `payment_id` should be provided to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) via the `payment_initiation.payment_id` parameter. Initializing Link with the returned `link_token` will launch the Payment Initiation flow.

##### Authenticate your app 

The endpoint used to create a `link_token` should only be available to users that are logged in to your app. Once your user is logged in, pass an identifier that uniquely identifies your user into the `user.client_user_id` field. The value of this field should not be personally identifiable information such as an email address or phone number. Using `user.client_user_id` will allow for easier debugging in the [Dashboard logs](https://dashboard.plaid.com/activity/logs) . You will be able to search for Link logs that belong to one of your end users.

As this update involves an additional API call when adding an Item, create a `link_token` when your user initially visits your app to avoid adding latency to your Link flow.

#### Update your client 

For each of your web and mobile apps, use the new endpoint you created to fetch a `link_token`, then pass it into one of Plaid's Link SDKs to initialize Link. You can then safely remove the `public_key` and other client-side configs that are now configured in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request.

If the token expires or the user enters too many invalid credentials, the `link_token` can become invalidated. If it does get into an invalid state, Link will exit with an [INVALID\_LINK\_TOKEN](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_link_token) error code. By recognizing when this error occurs in the `onExit` callback, you can generate a fresh `link_token` for the next time your user opens Link.

##### Update Link web 

The code below demonstrates code that passes the new `link_token` to Link. For more in-depth coverage on how to integrate with Link web, see the [Link web docs](https://plaid.com/docs/link/web/index.html.md) .

Note that in the error handling section, in order to handle an invalid `link_token` for Link in the browser, you will need to gracefully clean up the old iframe before reinitializing Link. To do this, use the `destroy()` method and reinitialize Link with a new `link_token` in the `onExit` callback.

```javascript
Link Account


(async function() {
  const fetchLinkToken = async () => {
    const response = await fetch('/create_link_token', { method: 'POST' });
    const responseJSON = await response.json();
    return responseJSON.link_token;
  };


  const configs = {
    // 1. Pass a new link_token to Link.
    token: await fetchLinkToken(),
    onSuccess: async function(public_token, metadata) {
      // 2a. Send the public_token to your app server.
      // The onSuccess function is called when the user has successfully
      // authenticated and selected an account to use.
      await fetch('/exchange_public_token', {
        method: 'POST',
        body: JSON.stringify({ public_token: public_token }),
      });
    },
    onExit: async function(err, metadata) {
      // 2b. Gracefully handle the invalid link token error. A link token
      // can become invalidated if it expires, has already been used
      // for a link session, or is associated with too many invalid logins.
      if (err != null && err.error_code === 'INVALID_LINK_TOKEN') {
        linkHandler.destroy();
        linkHandler = Plaid.create({
          ...configs,
          token: await fetchLinkToken(),
        });
      }
      if (err != null) {
        // Handle any other types of errors.
      }
      // metadata contains information about the institution that the
      // user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
  };


  var linkHandler = Plaid.create(configs);


  document.getElementById('link-button').onclick = function() {
    linkHandler.open();
  };
})();

```

##### Update Link iOS 

The iOS SDK now provides an `initWithLinkToken` method on both the `PLKConfiguration` and the `PLKPlaidLinkViewController` classes that should allow you to easily initialize Link with a `link_token`.

The code below shows how to initialize Link with the `link_token` in iOS. For more in-depth coverage on how to integrate with Link iOS, see the [iOS docs](https://plaid.com/docs/link/ios/index.html.md) .

```clike
let linkConfiguration = PLKConfiguration(linkToken: "GENERATED_LINK_TOKEN")
let linkViewDelegate = self
let linkViewController = PLKPlaidLinkViewController(
  linkToken: "GENERATED_LINK_TOKEN",
  configuration: linkConfiguration,
  delegate: linkViewDelegate,
)
if (UI_USER_INTERFACE_IDIOM() == .pad) {
    linkViewController.modalPresentationStyle = .formSheet;
}
present(linkViewController, animated: true)
```

##### Update Link Android 

The Android SDK exposes a new class called `LinkTokenConfiguration`. This class accepts the `link_token` and should be passed into the `openPlaidLink` method.

The code below demonstrates how to use the `LinkTokenConfiguration` class to open Link. For more in depth coverage on the Android SDK, see the [Android docs](https://plaid.com/docs/link/android/index.html.md) .

```typescript
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity


import com.plaid.link.Plaid
import com.plaid.link.linkTokenConfiguration
import com.plaid.link.openPlaidLink
import com.plaid.link.configuration.AccountSubtype
import com.plaid.link.configuration.LinkLogLevel
import com.plaid.link.configuration.PlaidEnvironment
import com.plaid.link.configuration.PlaidProduct
import com.plaid.link.event.LinkEvent
import java.util.Locale


class MainActivity : AppCompatActivity() {


  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)


    // Optional
    Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }


    // Open Link – put this inside of a Button / Fab click listener
    this@MAINACTIVITY.openPlaidLink(
      linkTokenConfiguration {
        // required
        token = "GENERATED_LINK_TOKEN"


        // optional
        logLevel = LinkLogLevel.WARN // Defaults to ASSERT
        extraParams = mapOf() // Map of additional configs
      }
    );
  }
}
```

#### Update Link update mode flows 

With the introduction of the `link_token`, `/item/public_token/create` is deprecated, and Link's update mode is initialized by passing in a `link_token` rather than a `public_token`. You can obtain this `link_token` by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and providing the `user.id` of the user whose Item is being updated, along with the `access_token` for the Item. Make sure to update any update mode flow entry points in addition to updating primary Link flows. For more details and complete sample code, see [Updating Items via Link](https://plaid.com/docs/link/update-mode/index.html.md) .

```javascript
// Initialize Link with the token parameter
// set to the generated link_token for the Item
const linkHandler = Plaid.create({
  token: 'GENERATED_LINK_TOKEN',
  onSuccess: (public_token, metadata) => {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  // ...
});
```

#### Test in Sandbox 

Once you have updated both your app's client and server, it's time to test that your integration works. The best way to test is by using the test credentials in the Sandbox:

```json
username: user_good
password: pass_good
```

Test your error handling flow for `INVALID_LINK_TOKEN` by using the Sandbox test credentials to force an error:

```json
username: user_custom
password: { "force_error": "INVALID_LINK_TOKEN" }
```

You can also verify that you have updated correctly by viewing Link event logs in the [Plaid Dashboard](https://dashboard.plaid.com/activity/logs) .

To test your update mode implementation, use the [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) endpoint to force an Item into a state that requires an update, then walk through the test steps above.

#### Update API endpoints 

In order to completely migrate off of the `public_key`, there are a few Plaid API endpoints that should replace the `public_key` with the `client_id` and `secret`: [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) , [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) , and [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) .

Because the `client_id` and `secret` are now used to authenticate the endpoints above, they should only be called from your server. The ability to call them from the client has been removed in the latest client library updates.

#### Disable the public key 

After completing all of the above steps, you can now confidently disable the `public_key` via the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . This can be done on a per-environment basis, with different settings for Sandbox and Production, to help you test your migration. The `public_key` can also be disabled separately for Link and for the API. Disabling it for Link means you will be required to use the `link_token` to initialize Link. Disabling it for the API means that you will be required to use the `client_id` and `secret` to call [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) , [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) , and[/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) .

(An image of "Dashboard UI for disabling the public key. Options to disable for Link and API in Sandbox, Development, and Production. Save changes button present.")

It is recommended you disable the `public_key` as soon as possible to ensure that you do not accidentally add legacy `public_key`\-dependent code to your application.

#### Conclusion 

Congratulations on upgrading to the new `link_token`! If you require any help migrating to the `link_token` integration, please [contact Plaid Support](https://dashboard.plaid.com/support/new/product-and-development/developer-lifecycle/link) for assistance.

---


# Link - Link analytics and tracking | Plaid Docs

Link analytics and tracking 
============================

#### Learn how to understand Link analytics and measure conversion 

#### Link Analytics 

Plaid instruments the actions users can take within the Link flow, allowing you to understand and measure a user's activity in Link. Pre-packaged summary views of some of the most important analytics are available within the Dashboard.

Note: Link sessions that use [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) are not included in Link Analytics.

(An image of "no description available")

The standard Link analytics view in Dashboard

##### Premium Link Analytics 

Customers on Premium Support Packages have access to Premium Link Analytics, which includes the following features:

*   Segment conversion performance and top errors by geography, institution, device type, product, and Link customizations
*   Compare against Plaid-wide benchmarks to identify strengths and opportunities
*   Review the Link funnel step by step, including key actions like `Institution Search` and `Submit Credentials`
*   Compare OAuth vs. non-OAuth funnels
*   View top Link errors as a percent of traffic
*   View top 10 institutions by Link opens and their conversion performance

To upgrade to a Premium Support Package, contact your Plaid Account Manager.

(An image of "no description available")

The premium Link analytics view in Dashboard

##### Auth and Identity Match conversion analytics 

If you use Auth or Identity Match, you can also use the [Account Verification Analytics Dashboard](https://dashboard.plaid.com/account-verification/analytics) to view more detailed product-specific analytics, including a conversion breakdown by Auth flow. This Dashboard is available at no additional charge to all Auth customers.

(An image of "image of Account Verification analytics")

##### Link analytics via MCP 

Support for Link analytics is available via Plaid's Dashboard MCP server, allowing you to analyze and interact with Link conversion data through chat or via an AI agent. For more details, see the [blog post on the Plaid Dashboard MCP server](https://plaid.com/blog/plaid-mcp-ai-assistant-claude/) and the [Plaid Dashboard MCP server documentation](https://plaid.com/docs/resources/mcp/index.html.md) .

#### Manual Link analytics 

To analyze Link activity in your own analytics platform, you can log and track Link actions yourself. This can be done either by tracking user activity on the frontend via the `onSuccess`, `onEvent`, and `onExit` callbacks, or via the backend, using the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint.

Link events are also tracked in the Dashboard via the [Developer Logs](https://dashboard.plaid.com/developers/logs) . However, the Developer Logs are designed for troubleshooting and not recommended for analytics use cases, as they cannot easily be exported to a third-party analytics platform.

This guide will go over the most important fields and events used for analytics, as well as the most popular analytics use cases. For a complete view of all user activity reporting that can be obtained from Link, see the documentation for the specific frontend platform SDK you are using (if tracking activity on the frontend) or for [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) (if tracking activity on the backend).

Link analytics activity names and structures will vary slightly depending on the platform you are using. For example, events fired by the Plaid iOS SDK use lowerCamelCase (e.g. `selectInstitution`) while events fired by the Plaid web SDK or returned by [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) use SCREAMING\_SNAKE (e.g. `SELECT_INSTITUTION`).

Similarly, [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) returns an `exit` object and an `events` array rather than firing the callbacks `onExit` and `onEvent`.

This guide will use the naming convention used by the web SDK. To see the exact naming syntax used by your platform, see the reference documentation for the specific SDK (or [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) ).

#### Tracking errors in Link 

The `onExit` callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. If the user encountered an error in the Link flow, the `error` object will obtain details of the most recently encountered error, including the `error.error_code`, `error.error_type`, and human-readable `error.error_message`.

```bash
{
  error_type: 'ITEM_ERROR',
  error_code: 'INVALID_CREDENTIALS',
  error_message: 'the credentials were not correct',
  display_message: 'The credentials were not correct.',
}
```

The [Link Analytics page](https://dashboard.plaid.com/link-analytics) in the Plaid Dashboard will show the five most common errors reported during the Link flow for your integration.

#### Tracking abandons in Link 

The `onExit` callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The `metadata.status` field within `onExit` field will reflect the point of the Link flow where the user abandoned the flow, and the `metadata.institution` field will reflect which institution the user was attempting to connect to.

```bash
{
  institution: {
    name: 'Citizens Bank',
    institution_id: 'ins_20'
  },
  status: 'requires_credentials',
  link_session_id: '36e201e0-2280-46f0-a6ee-6d417b450438',
  request_id: '8C7jNbDScC24THu'
}
```

#### Tracking the user journey in Link 

For almost every action your user takes within the Link flow, the `onEvent` callback will fire, allowing you to track their progress through Link. The `eventName` provided within `onEvent` typically corresponds to an action the user has taken in Link or an outcome that has occurred.

The most important event names include `OPEN` (the user has opened Link), `TRANSITION_VIEW` (the user has progressed to a new pane in Link), `HANDOFF` (the user has successfully completed Link), `ERROR` (a recoverable error has occurred in Link), and `EXIT` (the user has closed Link without completing it).

The event names you should track will depend on your use case and the Plaid products you use. For a complete listing of event names, see the reference documentation for your SDK (or [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) ).

Complete event activity is only available for a Link session once it has finished. Plaid does not provide the ability to track the status of an active Link session in real time. Event callbacks are not guaranteed to fire in the order in which they occurred. If you need to determine the ordering of events, sort by the `timestamp` field in the `metadata` object.

```json
OPEN
TRANSITION_VIEW
SELECT_INSTITUTION
TRANSITION_VIEW
SUBMIT_CREDENTIALS
TRANSITION_VIEW
HANDOFF
```

```json
OPEN
TRANSITION_VIEW
SELECT_INSTITUTION
TRANSITION_VIEW
SUBMIT_CREDENTIALS
TRANSITION_VIEW
ERROR
TRANSITION_VIEW
SUBMIT_CREDENTIALS
TRANSITION_VIEW
ERROR
TRANSITION_VIEW
EXIT
```

##### View names 

For a more granular view of a user's experience in Link, you can also record the `metadata.viewName` within `onEvent`. While the `eventName` typically reflects the action taken by the user or the result of their action, the `viewName` reflects the name of the specific Link pane being shown to the user, such as `ACCEPT_TOS` (asking the user to consent to the Plaid Terms of Service) or `OAUTH` (informing the user that they will be handed off to their institution's OAuth flow).

#### Measuring Link conversion 

You can view your Link conversion by viewing the [Link > Analytics page](https://dashboard.plaid.com/link-analytics) in the Plaid Dashboard. If you use Auth or Identity Match, you can also use the [Account Verification Analytics Dashboard](https://dashboard.plaid.com/account-verification/analytics) to view more detailed product-specific analytics, including a conversion breakdown by Auth flow.

Alternatively, you can set up your own conversion tracking. Tracking conversion on your own is recommended if you want more detailed analytics than reported in the Dashboard (for example, to perform A/B testing on Link conversion) or to connect Link conversion to your company's analytics platform.

For tracking conversion, the most important events are `HANDOFF`, which indicates that the user has linked an Item, and `EXIT`, which indicates that the user has exited without linking an account.

Your overall conversion rate is measured as the number of `HANDOFF` events divided by the number of unique `link_session_id`s. Alternatively, you can divide by the sum total of `HANDOFF` and `EXIT` events, but this method is less accurate, since an `EXIT` event will not fire if a user destroys Link by quitting the browser or closing the tab. You can obtain insight into at what point a user abandoned Link by tracking the `metadata.status` field within `onExit`.

```json
...
SELECT_INSTITUTION
TRANSITION_VIEW (view_name = OAUTH)
OPEN_OAUTH
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
```

```json
...
SELECT_INSTITUTION
TRANSITION_VIEW (view_name = CREDENTIAL)
SUBMIT_CREDENTIALS
TRANSITION_VIEW (view_name = MFA, mfa_type = code)
SUBMIT_MFA (mfa_type = code)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
```

You can also capture the `institution_name` field, provided by the `onEvent` callback, to track which institutions your users are attempting to connect to.

##### Measuring conversion for Identity Verification 

Because Identity Verification sessions trigger a unique set of events, you will need to use a slightly different method for calculating Identity Verification Link conversion, based on the `IDENTITY_VERIFICATION_START_STEP`, `IDENTITY_VERIFICATION_FAIL_SESSION` and `IDENTITY_VERIFICATION_PASS_SESSION` events. For details, see [Identity Verification Reporting](https://plaid.com/docs/identity-verification/reporting/index.html.md) .

#### Analyzing conversion data 

Many customers use third-party analytics platforms to analyze conversion data, which can allow you to easily view data by platform or institution. Lower conversion on a specific platform or institution may indicate an implementation problem. For example, lower conversion on mobile for OAuth-supporting institutions may indicate an issue with the handling of [OAuth redirects](https://plaid.com/docs/link/oauth/index.html.md#reinitializing-link) or failure to implement [app-to-app](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) .

We recommend tracking conversion data over time to measure the impact of changes to your Link integration.

##### Next steps 

Once you're measuring Link conversion, make sure you're maximizing it. For tips, see [Optimizing Link conversion](https://plaid.com/docs/link/best-practices/index.html.md) .

---


# Link - Pre-Link messaging | Plaid Docs

Link messaging 
===============

#### Shape your messaging around Link to optimize conversion and user experience 

#### Overview 

Factors that you control, such as how Link is placed in your onboarding flow, and the UI of the page where it is hosted, can have large impacts on Link conversion. This article outlines best practices for Link presentation that you can adopt to maximize conversion and overall user experience.

#### Pre-Link messaging best practices 

##### Explain the benefit to the user 

Your UI should tell the user why they want to use Link. For example, linking an account might let them make free transfers, versus having to pay a credit card transaction fee. Or it might be faster, allowing them to avoid manual data entry of balances or transactions, or having to wait several days for a micro-deposit-based verification flow.

##### Tell the user what to expect, including what data is shared and why 

Before launching the Link flow, explain to the user that they'll be prompted to link a bank account with Plaid. Explain what data your app will be collecting from their account, and why it's needed. One common approach is to provide a concise, user-friendly explanation of how your app uses data from Plaid, then link to your Privacy Policy for a more comprehensive explanation.

##### Present Link as the default 

Rather than presenting Link and manual flows as equal alternatives, encourage your customers to use Link through the size, positioning, and color of the Link entry point. You can also use labels such as "Recommended" or "Preferred". Yet another option is to display manual flows as an option only after the `onExit` callback (indicating a failed link attempt) has been received.

##### Explain that Link is secure 

Let customers know that Link is secure and uses 256-bit encryption; a lock icon can also be used to help convey that Link uses encryption. Explain that your app does not have access to their credentials. If your app implements the best practice of allowing users to [disconnect accounts from within the app](https://plaid.com/docs/link/messaging/index.html.md#allow-users-to-manage-linked-items) , explaining that they can choose to unlink their account later can increase users' confidence in their control over their data.

##### Do not use Plaid in your Link URL 

Using the string "Plaid" in the URL of the page from which Link is launched, especially in the subdomain (for example, [https://plaid.wonderwallet.com](https://plaid.wonderwallet.com) ) may cause customer confusion regarding the boundaries between your app and Plaid.

##### Provide a polished, engaging flow 

A Link hosting flow that is engaging, polished, and reflects your brand conveys the legitimacy and importance of linking an account. Illustrations and interactive elements can all be a part of your pre-Link messaging.

##### Be concise 

In applying the recommendations, use concise explanations, rather than displaying large blocks of text. If you need to provide more details to fully explain something, you can use a "learn more" link to display a modal with additional information.

##### Use multiple channels to engage users 

If a user does not link an account during their first interaction with your app, you can use other channels such as email, text, or mobile notifications to remind them. These channels should use the same best practices as your in-app UI. You can also use these channels to notify users when they need to take action to repair a linked account via [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

#### Pre-Link messaging examples 

Below are some examples of fictional Plaid-powered apps that incorporate elements of best-practice messaging. While every app will have its own unique pre-Link UI, these examples are intended to provide inspiration and demonstrate how the principles above can be applied.

##### Payments example 

(An image of "Settings page showing payment methods and Plaid bank verification options with instant and secure account linking features.")

This pre-Link flow conveys the benefit to the user, presents Link as the default experience, and uses social proof to show that Link is a secure solution trusted by many users. It mentions Plaid by name before launching the Link flow, helping the user understand that Plaid is trusted by the app. It also clearly explains what customer-permissioned data the app will be using, how that data will be used, and that the user can revoke access to that data.

##### Lending examples 

(An image of "Two mobile screens showing loan application steps: Left screen offers income verification via 'Connect Bank' button; right screen highlights benefits of linking bank for faster approval, better rates, and fund access.")

These pre-Link panes convey the benefit to the user of linking an account, present Link as the default experience, and explain that Link is secure.

##### Personal financial management example 

(An image of "Mobile app screens showing Neo Budget features: overdraft protection, pay advances, budget tracker, data safety with AES-256 encryption.")

This pre-Link pane conveys the benefit to the user, explains that Link is secure, and contains a link to additional security messaging with more detail on security practices, including an explanation of how the user can manage their linked account.

##### Email messaging example 

(An image of "Email from Neo Budget prompting user to connect bank via Plaid for features like overdraft alerts, pay advances, and budget tracking.")

This followup email, sent when a user does not link an account within 24 hours of signing up for the app, uses the same branding as the main app, contains a clear call to action, and explains the benefits of Link and why the user should link their account.

#### Post-Link messaging best practices 

While post-Link messaging has a less direct impact on conversion, it can still impact the confidence your users have in Plaid and in your app.

##### Present a success screen 

Let the user know that they successfully linked their account to your app. You can also show some of the data that your app has collected, so that the user can have proof that the link process worked correctly. If applicable, have a CTA on this screen that allows them to link another account.

##### Allow users to manage linked Items 

Having an area within your app where users can view, manage, or remove linked Items is a privacy and security best practice. It can also minimize the risk of [duplicate Items](https://plaid.com/docs/link/duplicate-items/index.html.md) (when a user accidentally adds the same Item twice) and help users fix Items that are unhealthy and need to go through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

#### Post-Link messaging example 

(An image of "Account ending in \*\*3345 successfully connected. Option to connect another account for better rates with 'Connect Another' button.")

This post-Link pane includes a success screen to instill confidence. It incorporates the account mask, which lets the user know their account data was retrieved, and incorporates a call to action to link another account.

#### Next steps 

To measure the impact of these steps or set up an experiment to evaluate them, see [Measuring Link conversion](https://plaid.com/docs/link/measuring-conversion/index.html.md) . For more conversion maximization tips, see [Maximizing Link conversion](https://plaid.com/docs/link/best-practices/index.html.md) .

---


# Link - Modular Link (UK/EU only) | Plaid Docs

Modular Link (UK/EU) 
=====================

#### Guide to implementing customised Link flows 

#### Introduction 

For UK/EU OAuth flows, Plaid offers Modular Link: a fully customisable end-to-end flow that maintains the best-in-class developer experience of Link. With Modular Link, you can create your own:

*   Institution selection pane
*   Loading states
*   Confirmation/Error panes

Modular Link is not enabled by default in any Plaid environment, even if you are already enabled for Payment Initiation. To request that your account be enabled for Modular Link, contact your Plaid Account Manager.

#### Link token creation 

For Modular Link flows, Link tokens must be initialised with an `institution_id` and `eu_config` object. Calling the [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint will return a list of objects representing institutions supported by Plaid. In this case, you'll want to set both `options.oauth` and `options.include_optional_metadata` to `true`. Each institution in the response will include a `name`, `logo`, and `institution_id`. You can use the `name` and `logo` to create an institution selection pane. After the user selects an institution, pass the corresponding `institution_id` into the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call.

For the `eu_config` object, the `headless` boolean is by default set to `false`. When it’s set to `true`, Link will not display any visual UI but will still handle redirects and communication with the bank in the background.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});


const client = new PlaidApi(configuration);


app.post('/api/create_link_token', async function (request, response) {
  const configs = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: 'user-id',
    },
    client_name: 'Plaid Test App',
    products: [Products.PaymentInitiation],
    language: 'en',
    webhook: 'https://webhook.sample.com',
    country_codes: [CountryCode.Gb],
    payment_initiation: {
      payment_id: paymentID,
    },
    eu_config: {
      headless: true,
    },
    institution_id: 'USER_SELECTED_INSTITUTION_ID',
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(configs);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

#### Mobile SDK initialisation 

For Android and iOS flows, follow the instructions in the [Android](https://plaid.com/docs/link/android/index.html.md) and [iOS](https://plaid.com/docs/link/ios/index.html.md) guides. The only change is in the `LinkTokenConfiguration`, where you will set `noLoadingState` to `true`. When this field is set, Plaid will not show any of its own loading states.

##### Android configuration 

```typescript
val linkTokenConfiguration = linkTokenConfiguration {
  token = "LINK_TOKEN_FROM_SERVER"
  noLoadingState = true
}
```

##### iOS configuration 

```clike
var linkConfiguration = LinkTokenConfiguration(
    token: "<#LINK_TOKEN_FROM_SERVER#>",
    onSuccess: { linkSuccess in
        // Send the linkSuccess.publicToken to your app server.
    }
)


linkConfiguration.noLoadingState = true
```

#### Custom loading states 

Once Plaid is initialised, you can begin displaying your loading animation. Link will handle the redirect to the bank and you can leave the loading state running in the background. After the user is done authenticating, Plaid will redirect back to your application where the loading state is still running.

#### Confirmation and error panes 

Plaid uses callbacks to indicate success or error states that enable you to present your custom screens. `onSuccess` will be called for successful payments and `onExit` will be called for flows ending in errors.

---


# Link - Multi-Item Link | Plaid Docs

Multi-Item Link 
================

#### Allow end users to connect accounts from multiple institutions in a single Link session 

#### Overview 

Multi-Item Link allows end users to add multiple Items in the same Link session. This flow is designed for contexts where you expect the user to link multiple accounts; for example, to provide a complete financial picture for a lending or personal finance use case.

Multi-Item Link can result in more Items being connected per user, due to reduced friction, and can simplify your app's logic and user experience.

Multi-Item Link is compatible with the following Plaid products: Auth, Transfer, Transactions, Liabilities, Investments, Bank Income, Assets, and Plaid Check Consumer Reports (including Income and Partner Insights). It does not require special enablement and is automatically available to all customers.

Multi-Item Link is not compatible with [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) . Multi-Item Link is also not currently compatible with [non-credential based Auth flows](https://plaid.com/docs/auth/coverage/same-day/index.html.md) such as Database Auth, Same Day Micro-Deposits, or Instant Micro-deposits.

(An image of "Success screen showing 2 connected institutions, Gingham Bank and Herringbone Treasury, with option to add another and Continue button.")

#### Integration process 

##### Creating a Link token 

First, create a user token using the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint.

```bash
// client_user_id is your own internal identifier for the end user
{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "client_user_id" : "c0e2c4ee-b763-4af5-cfe9-46a46bce883d" 
}
```

Next, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the `user_token` you just created, and the `enable_multi_item_link` field set to `true`.

```bash
// Sample link/token/create request
{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "client_name" : "Plaid Test App",
    "user_token":  "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce9",
    "enable_multi_item_link": true,
    "user": {
        "client_user_id": "c0e2c4ee-b763-4af5-cfe9-46a46bce883d",
    },
    "products": ["transactions"],
    "country_codes": ["US"],
    "language": "en",
}
```

Once you have created a Link token, you will launch [Link](https://plaid.com/docs/link/index.html.md) as normal, according to the standard instructions for your platform.

##### Obtaining a public token 

In most other Plaid integration methods, upon completion of the Link flow, you will receive a public token via the `onSuccess` callback. In a Multi-Item Link session, the `onSuccess` callback will be empty, and you will instead receive information about the Link flow (including the `public_token` array) via the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook.

When the entire Multi-Item Link flow is complete and the user has exited Link, Plaid will fire a [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook that contains information about what caused the session to end, as well as the public tokens if the session completed successfully.

```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"
}
```

If you want to start getting results as soon as each Item is added, you can listen for the [ITEM\_ADD\_RESULT](https://plaid.com/docs/api/link/index.html.md#item_add_result) webhook, which will fire after each completed Item add within the Link session.

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

Detailed session data, including the public tokens and account metadata, will also be available from [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) for six hours after the session has completed. In general, it is recommended to use the webhook to obtain the public token, since it will allow you to get the public token more promptly, but you may want to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) if your integration does not use webhooks, or as a backup mechanism if your system missed webhooks due to an outage.

When using Multi-Item Link, make sure to obtain the `public_token` from either the `SESSION_FINISHED` webhook, the `ITEM_ADD_RESULT` webhook, or the `results.item_add_results` object returned by [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . The `on_success` object returned by [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) is deprecated and should not be used to obtain the public token in Multi-Item Link flows, as it will contain only one public token, rather than all of the public tokens from the session.

##### Frontend changes 

When using Multi-Item Link, the frontend `onSuccess` callback will be empty, but other callbacks, such as `onExit` and `onEvent`, will remain populated as usual. Frontend callbacks can still be used to signal the end of the Link session. If you need the metadata that is normally found in `onSuccess`, such as the institution id or account mask, you can obtain it from the `results.item_add_results` object returned by [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) .

#### Multi-Item Link with multiple products 

If you are using Multi-Item Link, the same Link token settings will be used for every Item in the Link flow. This means, for example, that Auth with Same Day Micro-deposits cannot be used in the same Multi-Item Link flow as Income, because Auth must be initialized by itself to be used with Same Day Micro-deposits.

##### Using Auth or Transfer with Multi-Item Link 

A common use case for including Auth or Transfer as part of a Multi-Item link process is when you want one of the linked accounts to be used for sending or receiving payments. For example, as a lender, you may want to disburse the user's loan to a linked account, or as a financial management app, you may want to use one of the linked accounts to collect a monthly subscription fee.

In this situation, your app will want to connect to multiple institutions, but only need one account for payment purposes. For this use case, the recommended flow is:

1.  Put `auth` or `transfer` in the `optional_products` array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; this will request Auth or Transfer permissions when possible, but will not block linking accounts that don't support Auth and won't cause you to be billed for Auth unless you use an Auth endpoint on the Item.
    
2.  Locate eligible accounts by looking at the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) response object and traversing `link_sessions.results.item_add_results[].account[].subtype` to check each account on each Item, to see if it is of subtype `checking` or `savings`.
    
3.  For each Item on an account where the subtype is `checking` or `savings`, call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) and check the `item.products[]` array for `auth`.
    
4.  If the account subtype is `checking` or `savings`, and the `item.products[]` value contains `"auth"` as a value, then the account is eligible for use with Plaid Auth or Transfer. Present a UI in which the user can select an eligible account to use for sending or receiving funds. To avoid confusion, it is recommended that you present this UI even if there is only one eligible account.
    
5.  (Optional) You can add a button to this UI to link a different account to use for funds transfer, and have that button launch Link with just `auth` or `transfer`, which could allow the end user to link a payment account via a non-credential-based flow, such as Same Day Micro-Deposits or Database Insights.
    
6.  Once the user has selected an account to use for payments, call the appropriate endpoint, such as [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , on the corresponding Item.

---


# Link - OAuth guide | Plaid Docs

OAuth Guide 
============

#### Configure Link to connect to institutions via OAuth 

Prefer to learn by watching? Video guides are available for this topic.

*   [iOS Video Tutorial: OAuth section](https:///youtu.be/9fgmW38usTo&t=2608s)
*   [OAuth overview and guide for web](https://youtu.be/E0GwNBFVGik)
*   [OAuth video guide for Android](https://youtu.be/oM7vL49I5tc)

#### Introduction to OAuth 

OAuth support is required in all Plaid integrations that connect to financial institutions in the US, EU, and UK. Without OAuth support, your end users will not be able to connect accounts from institutions that require OAuth, which includes many of the largest banks in the US, and all financial institutions in Europe. OAuth setup can be skipped only if your Plaid integration is limited to products that do not connect to financial institutions (Enrich, Identity Verification, Monitor, Beacon, and Document Income).

OAuth is an industry-standard framework for authorization. With OAuth, end users can grant third parties access to their data without sharing their credentials directly with the third party.

Typically, end users authenticate and permission data directly within Plaid Link when connecting their financial accounts to third party applications. With OAuth, however, end users temporarily leave Link to authenticate and authorize data sharing using the institution's website or mobile app instead. Afterward, they're redirected back to Link to complete the Link flow and return control to the third party application.

(An image of "Plaid Link OAuth flow: Select bank, log in at Gingham Bank, authenticate, select accounts to share, account linked successfully.")

A typical OAuth flow with Plaid Link

In addition, Plaid integrations with OAuth have several benefits over the traditional, non-OAuth experience in Link, such as:

*   **Familiar and trustworthy experiences** With OAuth, end users authenticate via the bank's website or mobile app, a familiar experience that can help with conversion.
    
*   **Streamlined login experiences** Some OAuth-enabled institutions (e.g., Chase) provide an "App-to-App" experience for end users if the end user has the institution's mobile app installed on their device. App-to-App can provide alternative authentication methods to end users (e.g., Touch ID or Face ID) that can help simplify and accelerate the authentication process.
    
*   **Greater connection uptime** You can generally expect greater connection uptime with OAuth-enabled institutions, which means fewer connection errors for end users when using Plaid Link.
    
*   **Longer-lived connections** Items at OAuth-enabled institutions generally remain connected longer. This typically results in fewer re-authentication errors (e.g., `ITEM_LOGIN_REQUIRED`).
    
*   **Improved MFA (multi/second-factor) support** OAuth-enabled institutions can support end user accounts that may be currently unsupported due to the end user's MFA settings.
    

#### OAuth support and compatibility 

OAuth is supported on all platforms on which Link is supported.

Plaid supports the OAuth2 protocol. For a list of the largest Plaid-supported institutions that use OAuth in the US, consult the [OAuth institutions page](https://dashboard.plaid.com/settings/compliance/us-oauth-institutions) . For a full list of institutions, call [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint with your desired `country_codes` and the `oauth` option set to `true`. Note that for an institution where a migration to OAuth is in progress, some Items may use OAuth, while other Items at the same institution may not.

In general, OAuth connections are used universally by financial institutions in the UK and EU, are used by a number of financial institutions, especially larger ones, in the United States, and are not currently used by financial institutions in Canada.

#### Prerequisites for adding OAuth support 

##### Request Production access from Plaid 

[Full Production access](https://dashboard.plaid.com/overview/production) is a prerequisite for supporting OAuth. Plaid will contact you once your account has been enabled for Production.

In the US, OAuth requires full Production access. You can test OAuth in the Sandbox environment, using Sandbox-only institutions, without needing Production approval.

##### Complete the registration requirements 

Before implementing support for OAuth institutions, be sure to [complete the registration requirements](https://dashboard.plaid.com/settings/compliance/us-oauth-institutions) in the Plaid Dashboard.

**Application display information** – This is public information that end users of your application will see when managing connections between your application and their bank accounts, including during OAuth flows. This information helps end users understand what your application is and why it is requesting access, which can improve conversion. In addition, some US institutions require your profile to be completed and will not allow apps with an empty profile to access their OAuth implementations.

**Company information** – Information about your company. This information is not shared with end users of your application and is only accessible to Plaid, members of your team, and financial institutions you register with.

If you later need to update your company information or application display information, you can do so at any time via the Dashboard. If your company's name changes, in addition to updating the Dashboard, you will also need to contact your Account Manager in order for the change to be reflected in the OAuth flows for certain institutions, such as Charles Schwab and Capital One. If you do not have an Account Manager, you can [contact support](https://dashboard.plaid.com/support/new/admin/account-administration/oauth-registration) .

**Plaid Master Services Agreement (MSA)** – (US/CA only) Your latest contract with Plaid. If this is marked as incomplete, please reach out to your account manager or [contact support](https://dashboard.plaid.com/support/new/product-and-development/account-administration/oauth-registration) for an updated version.

**Plaid security questionnaire** – (US/CA only) You must complete a questionnaire about your company's risk and security practices before accessing certain bank APIs. Because it may take some time for Plaid to review, it is recommended that you submit this questionnaire as early as possible in the integration process. If your Plaid integration process is otherwise complete but your security questionnaire has not yet been approved, contact your account manager or [submit a Support ticket](https://dashboard.plaid.com/support/new/product-and-development/account-administration/oauth-registration) .

###### Legal Entity Identifier (LEI) 

Plaid is not currently enforcing the requirement to have an LEI and will not do so until the 1033 deadline, which is currently April 2026.

As part of your company information, you will be requested to optionally provide a Legal Entity Identifier, or LEI. The LEI is required under the [section 1033 rule](https://view-su2.highspot.com/viewer/a28391b5577027178f61d40b03f9c466) for any Plaid customer using OAuth connections to connect to US financial institutions. If your organization has multiple client ids, a unique LEI will be requested for each client id used in Production. Plaid is not currently enforcing the requirement to have an LEI. You can obtain an LEI from a [registration agent](https://www.gleif.org/en/about-lei/get-an-lei-find-lei-issuing-organizations) .

#### Implementing OAuth support 

##### Required steps 

1.  Wait for OAuth approval from Plaid, which can be tracked on the [OAuth institution page](https://dashboard.plaid.com/settings/compliance/us-oauth-institutions) .
    
2.  Understand [institution-specific behaviors](https://plaid.com/docs/link/oauth/index.html.md#institution-specific-behaviors) and, if necessary, update your app to support them.
    

##### Additional required steps for mobile implementations 

1.  [Create and register a redirect URI](https://plaid.com/docs/link/oauth/index.html.md#create-and-register-a-redirect-uri)
    
2.  [Generate a Link token and configure it with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri)
    
3.  [(Mobile web and webview integrations only) Support sessions launched in embedded browsers by reinitializing Link at your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#reinitializing-link)
    

##### Recommended, optional steps 

1.  [Handle Link OAuth events](https://plaid.com/docs/link/oauth/index.html.md#handling-link-events)
    
2.  [Listen for consent expiration webhooks](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent)
    
3.  [Manage consent revocation](https://plaid.com/docs/link/oauth/index.html.md#managing-consent-revocation)
    
4.  [(US/CA only) Enable OAuth and migrate users](https://plaid.com/docs/link/oauth/index.html.md#enabling-oauth-connections-and-migrating-users)
    
5.  [(Europe only) Enable QR Code authentication](https://plaid.com/docs/link/oauth/index.html.md#qr-code-authentication)
    

#### Create and register a redirect URI 

After successfully completing the OAuth flow via their bank's website or app, you'll need to redirect the end user back to your application. This is accomplished with a redirect URI that you'll need to set up and configure accordingly depending on your client platform.

Constructing valid redirect URIs

Redirect URIs must use HTTPS. The only exception is on Sandbox, where, for testing purposes, redirect URIs pointing to localhost are allowed over HTTP. Custom URI schemes are not supported in any environment. Subdomain wildcards are supported using a `*` character. For example, adding `https://*.example.com/oauth.html` to the allowlist permits `https://oauth1.example.com/oauth.html`, `https://oauth2.example.com/oauth.html`, etc. Subdomain wildcards can only be used for domains that you control and are not allowed for domains on the [Public Suffix List](https://publicsuffix.org/list/) . For example, `https://*.co.uk/oauth.html` is not a valid subdomain wildcard. Redirect URIs do not support hash routing, so your URI cannot contain a '#' symbol.

Note: Do not enter a wildcard (\*) when specifying a `redirect_uri` in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Wildcards are reserved for the allowlist on the dashboard only.

##### Desktop web, mobile web, React, or Webview 

For desktop web, mobile web, or React, the redirect URI is typically the address of a blank web page you'll need to create and host. This web page will be used to allow the end user to resume and complete the Link flow after completing the OAuth flow on their bank's website or app. `https://example.com/oauth-page.html` is an example of a typical redirect URI. After creating your redirect URI, add it to the [Allowed redirect URIs](https://dashboard.plaid.com/developers/api) .

Redirect URIs and desktop & mobile web

OAuth flows will function properly on web even if you don't set up a redirect URI. Desktop web and mobile web integrations will always try to open the OAuth bank's website in a new pop-up window if possible (or in a new tab on mobile web), regardless of whether a `redirect_uri` is provided. However, not providing a redirect URI will prevent mobile web users from using your integration through a webview browser (a browser launched via Mail, Facebook, Google Maps, etc.) because those browsers often do not support pop-ups. To provide the best experience for end users on mobile web, always specify a redirect URI and reinitialize Link.  
Setting a `redirect_uri` is still required for Link web SDK integrations within a mobile application (e.g within a webview) because those integrations still use the redirect OAuth flow.

##### iOS SDK, React Native (iOS) 

For iOS SDK or React Native (iOS), the redirect URI is typically the address of a blank web page you'll need to create and host. You'll need to configure an [Apple App Association File](https://developer.apple.com/documentation/security/password_autofill/setting_up_an_app_s_associated_domains) to associate your redirect URI with your application. To enable [App-to-App authentication flows](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) , you'll need to register the redirect URI as an app link. Custom URI schemes are not supported; a proper universal link **must** be used.

##### Android SDK, React Native (Android) 

Register your Android package by adding the Android package name(s) to the [Allowed Android package names](https://dashboard.plaid.com/developers/api) list. Plaid will automatically create your redirect URI and its contents based on your package name. When specifying a redirect URI in the following steps, you will use [android\_package\_name](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-android-package-name) .

#### Configure your Link token with your redirect URI 

You'll need to specify your redirect URI via the `redirect_uri` field when generating a Link token with [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) (on Android, use the `android_package_name` parameter to provide your Android package name instead). Use this Link token to initialize Link.

If you're using Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) , ensure you specify your redirect URI via the `redirect_uri` field (on Android, use the `android_package_name` parameter to provide your package name instead).

Do not use query parameters when specifying the `redirect_uri`. Make sure to specify the `user.client_user_id`.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const request = {
  user: {
    // This should correspond to a unique id for the current user.
    client_user_id: 'user-id',
  },
  client_name: 'Plaid Test App',
  products: [Products.Transactions],
  country_codes: [CountryCode.Us],
  language: 'en',
  webhook: 'https://sample-web-hook.com',
  redirect_uri: 'https://example.com/callback',
};


try {
  const createTokenResponse = await client.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

##### Using OAuth within an iFrame 

Launching Link from within an iFrame is not recommended. Link conversion for OAuth institutions is typically up to 15 percentage points higher when using Plaid's SDKs than when using iFrames. If Link is launched from within an iFrame, you'll be unable to maintain user state. Page rendering, sizing, and data exchange may also be suboptimal.

#### Reinitializing Link 

After completing the OAuth flow, the end user will be redirected to your redirect URI (e.g., `https://example.com/oauth-page.html`). This is where they'll resume and complete the Link flow and return to your application. To do this, you'll need to reinitialize Link at your redirect URI.

Depending on your client platform, Link may require additional configuration to work with OAuth. Detailed instructions for each platform are provided below.

| Client platform | Link reinitialization required? |
| --- | --- |
| [Desktop web](https://plaid.com/docs/link/oauth/index.html.md#desktop-web-mobile-web-or-react) | No |
| [Mobile web](https://plaid.com/docs/link/oauth/index.html.md#desktop-web-mobile-web-or-react) | Not required, but recommended in order to maximize Link conversion |
| [Webview](https://plaid.com/docs/link/oauth/index.html.md#webview) | Yes |
| [iOS SDK](https://plaid.com/docs/link/oauth/index.html.md#ios) | No |
| [React Native (iOS)](https://plaid.com/docs/link/oauth/index.html.md#react-native-on-ios) | No |
| Android SDK (version 3.2.3 or later required) | No, but [app package registration required](https://plaid.com/docs/link/oauth/index.html.md#android-sdk-react-native-android) |
| React Native (Android) | No, but [app package registration required](https://plaid.com/docs/link/oauth/index.html.md#android-sdk-react-native-android) |
| [Hosted Link](https://plaid.com/docs/link/oauth/index.html.md#hosted-link) | No |

##### Desktop web, mobile web, or React 

A reference implementation for OAuth in React can be found in the [Plaid React GitHub](https://github.com/plaid/react-plaid-link#oauth--opening-link-without-a-button-click) . If you are looking for a demonstration of a real-life app that incorporates the implementation of OAuth in React see [Plaid Pattern](https://github.com/plaid/pattern) , a Node-based example app.

Desktop and mobile web sessions do not require Link reinitialization by default.

However, not supporting Link reinitialization will prevent mobile web users from using your integration through a webview (an embedded browser launched via Mail, Facebook, Google Maps, etc.). For these sessions, you'll need to launch Link twice, once before the OAuth redirect (i.e., the first Link initialization) and once after the OAuth redirect (i.e., Link reinitialization). The Link reinitialization should occur at your redirect URI.

When reinitializing Link, configure it using the same Link token you used when [initializing Link the first time](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) . It is up to you to determine the best way to provide the correct `link_token` upon redirect. As an example, the code sample below demonstrates the use of a browser's local storage to retrieve the Link token from the first Link initialization.

Select group for content switcher

ReactVanilla JS

```tsx
import React, { useEffect } from 'react';
import { usePlaidLink } from 'react-plaid-link';


const OAuthLink = () => {
  // The Link token from the first Link initialization
  const linkToken = localStorage.getItem('link_token');


  const onSuccess = React.useCallback((public_token: string) => {
    // send public_token to server, retrieve access_token and item_id
    // return to "https://example.com" upon completion
  });


  const onExit = (err, metadata) => {
    // handle error...
  };


  const config: Parameters[0] = {
    token: linkToken!,
    // pass in the received redirect URI, which contains an OAuth state ID parameter that is required to
    // re-initialize Link
    receivedRedirectUri: window.location.href,
    onSuccess,
    onExit,
  };


  const { open, ready, error } = usePlaidLink(config);


  // automatically reinitialize Link
  useEffect(() => {
    if (ready) {
      open();
    }
  }, [ready, open]);


  return <>;
};


export default OAuthLink;
```

```javascript

    
    
      (function ($) {
        var linkToken = localStorage.getItem("link_token");
        var handler = Plaid.create({
          token: linkToken,
          // pass in the received redirect URI, which contains an OAuth state ID parameter that is required to
          // re-initialize Link
          receivedRedirectUri: window.location.href,
          onSuccess: function (public_token) {
            $.post(
              "/api/set_access_token",
              { public_token: public_token },
              function (data) {
                location.href = "https://example.com";
              }
            );
          },
        });
        handler.open();
      })(jQuery);
    
```

In addition, when reinitializing Link, you should configure it with the `receivedRedirectUri` field and pass in the full received redirect URI, as demonstrated in the code sample. The received redirect URI is your redirect URI appended with an OAuth state ID parameter. The OAuth state ID parameter will allow you to persist user state when reinitializing Link, allowing the end user to resume the Link flow where they left off. No extra configuration or setup is needed to generate the received redirect URI. The received redirect URI is programmatically generated for you by Plaid after the end user authenticates on their bank's website or mobile app. You can retrieve it using `window.location.href`.

The received redirect URI must not contain any extra query parameters or fragments other than what is provided upon redirect. The standard Link callback `onSuccess` will be triggered as usual once the user completes the Link flow.

```bash
https://example.com/oauth-page.html?oauth_state_id=9d5feadd-a873-43eb-97ba-422f35ce849b
```

###### Optional methods for retrieving the initial Link token 

If Link is reinitialized in the _same_ browser session as the first Link initialization, you can store the Link token in a cookie or local storage in the browser for easy access when reinitializing Link. For example, the Plaid Quickstart uses `localStorage.setItem` to store the token.

If Link is reinitialized in a _different_ browser session than the first Link initialization, you can store a mapping of the Link token associated with the user (server-side). Upon opening the second browser session, authenticate the user, fetch the corresponding Link token from the server, and use it to reinitialize Link.

##### Webview 

All webview-based integrations need to extend the webview handler for redirects in order to support Chase OAuth. This can be accomplished with code samples for [iOS](https://github.com/plaid/plaid-link-examples/blob/master/webviews/wkwebview/wkwebview/LinkViewController.swift#L56-L72) and [Android](https://github.com/plaid/plaid-link-examples/blob/master/webviews/android/LinkWebview/app/src/main/java/com/example/linkwebview/MainActivity.kt#L89-L156) For more details, see [Extending webview instances to support certain institutions](https://plaid.com/docs/link/oauth/index.html.md#extending-webview-instances-to-support-certain-institutions) .

For webview, you'll need to launch Link twice, once before the OAuth redirect (i.e., the first Link initialization) and once after the OAuth redirect (i.e., Link reinitialization). The Link reinitialization should occur at your redirect URI.

For the initial Link instance, first generate a Link token as described in [Configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) , then set Link's `token` parameter to this Link token. After the end user successfully completes the OAuth flow via their bank's website or app, they'll be redirected to your redirect URI, where you'll reinitialize Link.

```jsx
https://cdn.plaid.com/link/v2/stable/link.html?isWebview=true
&token=GENERATED_LINK_TOKEN
```

When reinitializing Link, use the same Link token you generated when you first initialized Link. It is up to you to determine the best way to provide the correct `link_token` upon redirect.

In addition, when reinitializing Link, you should configure it with the `receivedRedirectUri` field. The received redirect URI is your redirect URI appended with an OAuth state ID parameter. The OAuth state ID parameter will allow you to persist user state when reinitializing Link, allowing the end user to resume the Link flow where they left off. No extra configuration or setup is needed to generate the received redirect URI. The received redirect URI is programmatically generated after the end user authenticates on their bank's website or mobile app. The received redirect URI must not contain any extra query parameters or fragments other than what is provided upon redirect. Note that any unsafe ASCII characters in the `receivedRedirectUri` in the webview query string must be URL-encoded; for improved readability, the example below is shown prior to URL encoding.

```jsx
https://cdn.plaid.com/link/v2/stable/link.html?isWebview=true
&token=SAME_GENERATED_LINK_TOKEN&receivedRedirectUri=https://example.com/oauth-page?oauth_state_id=9d5feadd-a873-43eb-97ba-422f35ce849b
```

###### Extending webview instances to support certain institutions 

Some institutions require further modifications to work with mobile webviews. This applies to USAA on Android and Chase App-to-App on Android, as well as all Chase webview integrations. For these institutions, you'll need to extend your Webview instance to override the handler for redirects. [An example function for Android](https://github.com/plaid/plaid-link-examples/blob/master/webviews/android/LinkWebview/app/src/main/java/com/example/linkwebview/MainActivity.kt#L89-L156) and [an example function for iOS](https://github.com/plaid/plaid-link-examples/blob/master/webviews/wkwebview/wkwebview/LinkViewController.swift#L56-L72) can be found within Plaid's Link examples on GitHub and can be copied for use with your app.

On Android, you will also need to support Android App links to have a valid working `redirect_uri` to provide to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . This requires creating a `./well_known/assetlinks.json` and an `IntentFilter` on the Android app.

##### iOS 

For the initial Link instance, first generate a Link token as described in [Configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) . Your `redirect_uri` must also be added to the Plaid Dashboard and should be configured as a universal link (not a custom URI) using an Apple App Association File.

```clike
// With custom configuration
let linkToken = "<#GENERATED_LINK_TOKEN#>"
let onSuccess: (LinkSuccess) -> Void = { (success) in
  // Read success.publicToken here
  // Log/handle success.metadata here
}
let linkConfiguration = LinkTokenConfiguration(linkToken: linkToken, onSuccess: onSuccess)
let handlerResult = Plaid.create(linkConfiguration)


switch handlerResult {
case .success(let handler):
  self.handler = handler
  handler.open(presentUsing: .viewController(self))
case .failure(let error):
  // Log and handle the error here.
}
```

OAuth on iOS devices can occur fully within the integrating application (In-App OAuth), or it can include a transition from your application to the bank's app ([App-to-App OAuth](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) ). App-to-App OAuth is initiated by the bank itself and is not controlled by the iOS SDK. In order to ensure your users can return to your application, you must support App-to-App OAuth.

##### App-to-App OAuth requirements 

During App-to-App OAuth, the end user is directed from your application to the bank's app to authenticate. To return the end user back to your application after they authenticate, your redirect URI must be a universal link. Once the user returns to your app, UIKit will invoke a method within your application and provide the redirect URI that triggered this return to the app.

App-to-App behavior can be [tested in the Sandbox environment](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) . If App-to-App does not function as intended, validate that the redirect URI used to configure Link is a valid universal link and that your application has the associated-domains entitlement for that URI.

##### React Native on iOS 

An example React Native client implementation for OAuth on iOS can be found in the [Tiny Quickstart](https://github.com/plaid/tiny-quickstart/tree/main/react_native/TinyQuickstartReactNative) .

React Native on iOS uses universal links for OAuth. You will need to [create and register a redirect URI](https://plaid.com/docs/link/oauth/index.html.md#create-and-register-a-redirect-uri) and [configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) in order for OAuth to work correctly.

##### Android SDK and Android on React Native 

Example code for implementing OAuth on Android can be found on GitHub in the [Android SDK](https://github.com/plaid/plaid-link-android) . An example React Native client implementation for OAuth on Android can be found in the [Tiny Quickstart](https://github.com/plaid/tiny-quickstart/tree/main/react_native/TinyQuickstartReactNative) .

When using the Android SDK or Android on React Native, you must generate a Link token by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and passing in an `android_package_name`. Your package name (e.g., `com.example.testapp`) must also be added to the Plaid Dashboard. Do not pass a `redirect_uri` into the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. Proceed to initialize Link with the generated token.

Select group for content switcher

Current librariesLegacy libraries

```typescript
String clientUserId = "user-id";


LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser()
  .clientUserId(clientUserId)
  .legalName("legal name")
  .phoneNumber("4155558888")
  .emailAddress("email@address.com");


LinkTokenCreateRequest request = new LinkTokenCreateRequest()
  .user(user)
  .clientName("Plaid Test App")
  .products(Arrays.asList(Products.AUTH))
  .countryCodes(Arrays.asList(CountryCode.US))
  .language("en")
  .webhook("https://example.com/webhook")
  .linkCustomizationName("default")
  .androidPackageName("com.plaid.example")


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


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

##### Hosted Link 

Hosted Link can use universal links for flows in which the Hosted Link URL is used in a secure context webview within a mobile application. In this scenario, the universal link is used to redirect the user back to your app after the [app-to-app](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) flow is complete.

To do so, you will need to [create and register a redirect URI](https://plaid.com/docs/link/oauth/index.html.md#create-and-register-a-redirect-uri) for the universal link and [configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) . For more details on configuring universal links with Hosted Link, see [App-to-app authentication](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) .

For details on configuring your redirect URI for Hosted Link on mobile, see [Integrating Hosted Link in Native Mobile applications](https://plaid.com/docs/link/hosted-link/index.html.md#integrating-hosted-link-in-native-mobile-applications) .

#### Testing OAuth 

You can test OAuth in Sandbox even if Plaid has not yet enabled OAuth flows for your account. To test out the OAuth flow in the Sandbox environment, you can select any bank that supports OAuth (this includes institutions like Chase, U.S. Bank, Wells Fargo, and others) or use the Platypus OAuth Bank (`ins_127287`). For Europe, you can select Flexible Platypus Open Banking (`ins_117181`).

These institutions will direct you to a Plaid sample OAuth flow that is similar to what you would see for a bank’s OAuth flow. When prompted, you can enter anything as credentials (including leaving the input fields blank) to proceed through the sample OAuth flow. Note that institution-specific OAuth flows cannot be tested in Sandbox; OAuth panes for Platypus institutions will be shown instead.

The Platypus OAuth flow includes two optional "consent" checkboxes that reflect what a user might need to select in order to opt in to Auth and Identity. However, these checkboxes are not functional -- your application will receive the proper Auth and Identity data, even if you don't select those boxes during testing.

To ensure your OAuth integration works across all platforms, test it in the following scenarios before deployment:

*   On each client platform that is available to your users (e.g. desktop, iOS app, iOS mobile web, Android app, Android mobile web)
*   With the OAuth institution app installed, for institutions that support [app-to-app authentication](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) (i.e. Chase). To test app-to-app in Sandbox, use First Platypus Bank as the institution; see [App-to-App authentication](https://plaid.com/docs/link/oauth/index.html.md#app-to-app-authentication) for more details.
*   Without the OAuth institution app installed
*   In [update mode](https://plaid.com/docs/link/update-mode/index.html.md) , by using [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) in the Sandbox environment

All environments, including Sandbox, use the pop-up flow on desktop and mobile web, unless the page is accessed through a mobile webview. To test the redirect flow, you can use your browser's developer tools to simulate running your application in a webview browser, such as Chrome WebView. On Chrome, for example, select the "Toggle Device Toolbar" option from within Chrome's Developer Tools and create a new virtual device configuration with a WebView user agent.

```bash
Mozilla/5.0 (Linux; Android 5.1.1; Nexus 5 Build/LMY48B; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/43.0.2357.65 Mobile Safari/537.36
```

#### Troubleshooting common OAuth problems 

For guides to troubleshooting common OAuth issues, see [Link troubleshooting](https://plaid.com/docs/link/troubleshooting/index.html.md#oauth-not-working) .

#### Enabling OAuth connections and migrating users 

When an institution is newly enabled for OAuth connections, your integration will automatically convert to using OAuth connections for a given institution on the date that Plaid has indicated to you. You may also have the option to migrate to OAuth earlier; if this option is available, a button to enable OAuth for the institution will appear on the [OAuth institution page](https://dashboard.plaid.com/settings/compliance/us-oauth-institutions) .

For some institutions, migrating to OAuth will cause disruptions to existing Items. In this case, existing Items will be moved into the `ITEM_LOGIN_REQUIRED` state. This will happen gradually over the migration period (by default, 90 days, but the duration may vary depending on the institution), starting on or shortly after the OAuth enablement date. Completing the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow for these Items will convert them to use OAuth connections. To avoid any disruption in connectivity, you can also prompt your users to complete the update mode flow as soon as you have been enabled for OAuth with their institution.

To view which institutions are being migrated to OAuth connections, use the [migrations pane](https://dashboard.plaid.com/activity/status/migrations) within the Dashboard status page, or look up a specific institution in the status page to see its migration details, including the migration timeline and whether existing Items will be disrupted. For more details, see [Institution migration status](https://plaid.com/docs/account/activity/index.html.md#institution-migration-status) .

#### Institution-specific behaviors 

Some institutions have unique behaviors when used with OAuth connections. Note that these behaviors are standard for any connection using these institutions' APIs and not specific to their integration with Plaid.

The behaviors listed below are the ones most likely to require changes to your application's business logic; for a more exhaustive list of institution-specific OAuth details, including screenshots of the OAuth flows and summaries of data availability for several major institutions, see the [Plaid guide to institution-specific OAuth experiences](https://plaid.com/documents/oauth-institution-ux.pdf) .

##### Chase 

While most OAuth institutions grant OAuth access immediately upon full Production approval, Chase has an additional waiting period; it may take up to two weeks after Production approval for Chase Production access to be granted. You must also complete the Security Questionnaire before gaining access to Chase.

As of January 2025, the Chase additional waiting period is temporarily extended. If you are blocked from launching by this delay and require assistance, contact support or your Account Manager.

When used with Auth or Transfer, Chase will return tokenized routing and account numbers, which can be used for ACH transactions but are not the user's actual account and routing numbers. For important details on how to avoid user confusion and ACH returns, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) .

[Update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) cannot be used to remove accounts or permissions from a Chase Item. If your end user wishes to revoke or limit Plaid's access to a Chase account, they must do so via the Chase Security Center within the Chase online banking portal. This occurs even across Items; if a Chase Item is deleted and a new Item is created for your app using the same credentials, the previously selected permissions will persist to the new Item.

Existing Chase OAuth Items will be invalidated when a new public token is created using the same credentials, if the two Items do not have exactly the same set of accounts associated with them, or if either Item is used with a [Plaid Check](https://plaid.com/docs/check/index.html.md) product. For more details, see [Preventing duplicate Items](https://plaid.com/docs/link/duplicate-items/index.html.md#preventing-duplicate-items) .

##### Capital One 

When calling [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) for a Capital One non-depository account, such as a credit card or loan account, you will need to specify how fresh you require the balance data to be. If balance data meeting your requirements is not available, the call will fail and you will not be billed. For more details, see the [API Reference](https://plaid.com/docs/api/products/balance/index.html.md#accounts-balance-get-request-options-min-last-updated-datetime) . For similar reasons, [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) will result in a `PRODUCTS_NOT_SUPPORTED` error if used on a Capital One Item that includes only non-depository accounts.

Capital One Items require consent to be refreshed after one year.

Capital One (like several other institutions) does not provide pending transaction data.

Capital One does not allow end users to link credit cards whose payments are past due.

##### Charles Schwab 

While most OAuth institutions grant OAuth access immediately upon full Production approval, Schwab has an additional waiting period and it may take up to five weeks from Production approval until Schwab Production access has been granted. Pay-as-you-go customers will need to explicitly request access to Schwab by filing a ticket in the Dashboard.

Existing Charles Schwab OAuth Items will be invalidated when a new public token is created using the same credentials, if the two Items do not have exactly the same set of accounts associated with them, or if either Item is used with a [Plaid Check](https://plaid.com/docs/check/index.html.md) product. For more details, see [Preventing duplicate Items](https://plaid.com/docs/link/duplicate-items/index.html.md#preventing-duplicate-items) .

##### PNC 

When used with Auth or Transfer, PNC will return tokenized routing and account numbers, which can be used for ACH transactions but are not the user's actual account and routing numbers. For important details on how to avoid user confusion and ACH returns, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) .

When used with Auth or Transfer, PNC Items require consent to be refreshed after one year, with the first expirations to occur in October 2025. If consent expires, the tokenized account number will expire as well. For more details on this behavior, including how to renew consent, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) .

Existing PNC OAuth Items will be invalidated when a new public token is created using the same credentials, if the two Items do not have exactly the same set of accounts associated with them, or if either Item is used with a [Plaid Check](https://plaid.com/docs/check/index.html.md) product. For more details, see [Preventing duplicate Items](https://plaid.com/docs/link/duplicate-items/index.html.md#preventing-duplicate-items) .

##### US Bank 

When used with Auth or Transfer, US Bank will return tokenized routing and account numbers, which can be used for ACH transactions but are not the user's actual account and routing numbers. For important details on how to avoid user confusion and ACH returns, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) .

#### Handling Link events 

OAuth flows have a different sequence of [Link events](https://plaid.com/docs/link/web/index.html.md#onevent) than non-OAuth flows. If you are using Link events to measure conversion metrics for completing the Link process, you may need to handle these events differently when using OAuth.

In addition, the flow itself may be different if you are initiating OAuth with a redirect URI or displaying the OAuth screen in a separate pop-up window.

The events fired for a non-OAuth flow might look something like this:

```json
OPEN (view_name = CONSENT)
TRANSITION_VIEW view_name = SELECT_INSTITUTION)
SELECT_INSTITUTION
TRANSITION_VIEW (view_name = CREDENTIAL)
SUBMIT_CREDENTIALS
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = MFA, mfa_type = code)
SUBMIT_MFA (mfa_type = code)
TRANSITION_VIEW (view_name = LOADING)
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess
```

The events fired for a typical OAuth flow may look more like the following:

```json
OPEN (view_name = CONSENT)
TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
SELECT_INSTITUTION
TRANSITION_VIEW (view_name = OAUTH)
OPEN_OAUTH
...
(The user completes the OAuth flow at their bank)
...
TRANSITION_VIEW (view_name = CONNECTED)
HANDOFF
onSuccess
```

Link does not issue the `SUBMIT_CREDENTIALS` event when a user authenticates with an institution that requires OAuth. Link issues the `OPEN_OAUTH` event when a user chooses to be redirected to the institution’s OAuth portal. It is recommended to track this event instead of `SUBMIT_CREDENTIALS`.

In most situations, if Plaid encounters an error from the bank's OAuth flow, or if the user chooses to not grant access via their OAuth login attempt, the user will return to your application and Link will fire an `EXIT` event with a `requires_oauth` exit status. You may also see an `ERROR` event, depending on the type of error that Plaid encountered.

```json
SELECT_INSTITUTION
OPEN (view_name = null)
ERROR (error_code = INTERNAL_SERVER_ERROR)
TRANSITION_VIEW (view_name = ERROR)
TRANSITION_VIEW (view_name = EXIT)
EXIT (exit_status = requires_oauth)
```

If the user closes the bank's OAuth window without completing the OAuth flow, Link will fire a `CLOSE_OAUTH` event. This only happens in situations where the OAuth flow appears in a pop-up window.

If the OAuth flow times out while waiting for the user to sign in, Link will fire a `FAIL_OAUTH` event. This only happens in situations where the OAuth flow appears in a pop-up window.

Once you receive the `onSuccess` callback from an OAuth flow, the integration steps going forward are the same as for non-OAuth flows.

#### Refreshing Item consent 

When using OAuth, consent may expire after a certain amount of time and need to be refreshed. This is common in Europe, where consent typically expires after 180 days. In the US, the following institutions require periodic OAuth consent refresh. Consent refresh at these institutions is required every 12 months, unless noted otherwise.

*   American Express
*   Brex (3 months)
*   Capital One
*   Citibank
*   Navy Federal Credit Union
*   PNC
*   TD Bank
*   USAA (18 months)

Note that when an institution adopts a consent expiration policy, it is generally not applied retroactively. Instead, Items that existed prior to the requirement will be treated as though they were created on the day that the requirement was instituted.

To determine when consent expires, call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) and note the `consent_expiration_time` field. Plaid will also send a [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) webhook (for US/CA Items) or a [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) webhook (for UK/EU Items) one week before a user's consent is set to expire.

To refresh consent for an Item, send it through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

If consent is not refreshed before the Item expires, the Item will enter the `ITEM_LOGIN_REQUIRED` error state. Sending the Item through update mode will resolve the error.

For a real-life example of handling the `PENDING_EXPIRATION` webhook and update mode, see [handleItemWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleItemWebhook.js#L69-L86) , [linkTokens.js](https://github.com/plaid/pattern/blob/master/server/routes/linkTokens.js#L30-L35) and [launchLink.tsx](https://github.com/plaid/pattern/blob/master/client/src/components/LaunchLink.tsx#L42) . These files illustrate the code for handling of webhooks and update mode for Plaid Link for React for the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app.

#### Managing consent revocation 

Many institutions that support OAuth provide a means for the end user to revoke consent via their website. If an end user revokes consent, the Item will enter an `ITEM_LOGIN_REQUIRED` state after approximately 24-48 hours.

A user may also revoke consent for a single account, without revoking consent for the entire Item. Accounts in this situation are treated the same as accounts that have been closed: no webhook will be fired, you will stop receiving transactions associated with the account, and Plaid will stop returning the account in API responses. Access can be re-authorized via the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow.

When a user revokes access to an Item or an account, you should delete the associated data; the 1033 rule requires third parties to no longer use or retain covered data upon revocation unless use or retention of that covered data remains reasonably necessary to provide the consumer's requested product or service.

When using Link in update mode (for either case described in this section), be sure to specify your redirect URI via the `redirect_uri` field as described in [Configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) .

#### Scoped consent 

OAuth can provide the ability for end users to configure granular permissions on their Items. For example, an end user may allow access to a checking account but not a credit card account behind the same login, or may allow an institution to share only certain account information, such as identity data but not transaction history.

Before handing the user off to the institution's OAuth flow, Plaid will provide guidance within Link recommending which permissions the user needs to grant based on which products you have initialized Link with. In Production, this guidance will be tailored to use the same wording that the institution's OAuth flow uses. This guidance will appear both on initial link and during the [update mode flow](https://plaid.com/docs/link/update-mode/index.html.md) .

If an end user chooses not to share data that is required by your Link token's `products` or `required_if_supported_products` configuration, or does not share access to any accounts, Link will show an error, and they will be prompted to restart the Link flow.

Note that if your app calls [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) using an `account_filter` parameter to limit the account types that can be used with Link, the filter will only be applied after the OAuth flow has been completed and will not affect the permission selection interface within the OAuth flow.

If you do not have the product-specific OAuth permissions required to use a specific endpoint with an Item, you will receive an [ACCESS\_NOT\_GRANTED](https://plaid.com/docs/errors/item/index.html.md#access_not_granted) error. If you are missing permissions for an account on the Item, you may receive a product-specific error indicating that a compatible account could not be found, such as [NO\_AUTH\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_auth_accounts-or-no-depository-accounts) , [NO\_INVESTMENT\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_investment_accounts) , or [NO\_LIABILITY\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_liability_accounts) .

If your app later needs to request access to a product or account that was not originally granted for that Item during Link, you can send the user to the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow to authorize additional permissions. When using Link in update mode, be sure to specify your redirect URI via the `redirect_uri` field as described in [Configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) .

#### App-to-App authentication 

Some banks (i.e. Chase) support an App-to-App experience if the user is authenticating on their mobile device and has the bank's app installed. Instead of logging in via the bank's site, the bank's app will be launched instead, from which the user will be able to log in (including via TouchID or Face ID) before being redirected back to your app. Support for App-to-App should be automatic once you have implemented support for OAuth on mobile with any of Plaid's mobile SDKs. Note that on iOS, this requires configuring an Apple App Association file to associate your redirect URI with your app, as described under [Create and register a redirect URI](https://plaid.com/docs/link/oauth/index.html.md#create-and-register-a-redirect-uri) . If using webviews, App-to-App support is not automatic; for an App-to-App experience, it is strongly recommended to use a Plaid mobile SDK or Hosted Link instead. If you are using Hosted Link, ensure you are passing in a Universal Link as the `redirect_uri` parameter when creating a Link token using [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

The full App-to-App flow can be tested in the Sandbox environment. You can test that your universal link works correctly using the First Platypus Bank - OAuth App2App (`ins_132241`) test institution. The bank's 'app' for this test institution will be a mobile web browser, but the universal link will function as expected if configured correctly, switching back to your app on handoff. On iOS, you must use the Plaid Link SDK version 5.1.0 or later to test App-to-App in Sandbox.

Chase is currently the only US bank that supports App-to-App authentication on Plaid.

[Watch video](https://www.youtube.com/watch?v=RKmEbRbRNwY)

#### QR code authentication 

For many European institutions, Plaid supports the ability for an end user to authenticate via their bank's mobile app – even if the user's journey begins in a desktop-based web session – in order to optimize for conversion. After the user selects an institution, they will be presented with the choice to scan a QR code and authenticate in the bank’s mobile app or to continue on desktop. When the user scans the QR code, they will be redirected to the bank’s app (or website, if the user does not have the app installed). After the user completes the OAuth flow, they will be redirected to a Plaid-owned page instructing them to return to their desktop to complete the flow.

To enable QR authentication, contact your Plaid account manager or [file a Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . No changes to your Link OAuth implementation are required to enable this flow.

(An image of "Payment screen showing amount £21.23 for goods/services with 'Pay with bank' button on a Plaid OAuth integration page.")

To test out the QR code flow in the Sandbox environment, you can use Flexible Platypus Open Banking (`ins_117181`). When you launch Link with this institution selected in Sandbox, the QR code authentication flow will be triggered. The Sandbox institution does not direct you to a real bank's mobile app, but allows you to grant, deny, or simulate errors from the placeholder OAuth page instead.

##### Supported institutions for QR code authentication 

Below is a partial list of some of the institutions that support QR code authentication.

| Institution name | Institution ID |
| --- | --- |
| Bank of Scotland - Personal | `ins_118274` |
| Bank of Scotland - Business | `ins_118276` |
| Barclays (UK) - Mobile Banking: Business | `ins_118512` |
| Barclays (UK) - Mobile Banking: Personal | `ins_118511` |
| Barclays (UK) - Mobile Banking: Wealth Management | `ins_118513` |
| First Direct | `ins_81` |
| Halifax | `ins_117246` |
| HSBC (UK) - Business | `ins_118277` |
| HSBC (UK) - Personal | `ins_55` |
| Lloyds Bank - Business and Commercial | `ins_118275` |
| Lloyds Bank - Personal | `ins_61` |
| Monzo | `ins_117243` |
| Nationwide Building Society | `ins_60` |
| NatWest - Current Accounts | `ins_115643` |
| Revolut | `ins_63` |
| Royal Bank of Scotland - Current Accounts | `ins_115642` |
| Santander (UK) - Personal and Business | `ins_62` |
| Starling | `ins_117520` |
| Tesco (UK) | `ins_118393` |
| TSB | `ins_86` |
| Ulster Bank (UK) | `ins_117734` |

---


# Link - React Native | Plaid Docs

Link React Native SDK 
======================

#### Reference for integrating with the Link React Native SDK 

This guide covers the latest major version of the Link React Native SDK, which is version 12.x.x. For information on migrating from older versions, see [Migration guides](https://plaid.com/docs/link/react-native/index.html.md#migration-guides) .

#### Overview 

Prefer to learn with code examples? A [GitHub repo](https://github.com/plaid/tiny-quickstart/tree/main/react_native) showing a working example Link implementation is available for this topic.

To get started with [Plaid Link for React Native](https://github.com/plaid/react-native-plaid-link-sdk) youʼll want to sign up for [free API keys](https://dashboard.plaid.com/developers/keys) through the Plaid Dashboard.

(An image of "Plaid Link React Native flow: Connect account, select institution, enter credentials, choose account, connection success.")

#### Requirements 

*   React Native Version `0.66.0` or higher

New versions of the [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application.

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

##### Version Compatibility 

| React Native SDK | Android SDK | iOS SDK | Status |
| --- | --- | --- | --- |
| 12.x.x | 5.0+ | \>=6.0.0 | Active, supports Xcode 16 |
| 11.x.x | 4.1.1+ | \>=5.1.0 | Active, supports Xcode 15 |
| 10.x.x | 3.10.1+ | \>=4.1.0 | Active, supports Xcode 14 |
| 9.x.x | 3.10.1+ | \>=4.1.0 | Deprecated, supports Xcode 14 |

#### Getting Started 

##### Installing the SDK 

In your react-native project directory, run:

```bash
npm install --save react-native-plaid-link-sdk
```

##### iOS Setup 

Add Plaid to your project's Podfile as follows (likely located at ios/Podfile).

```bash
pod 'Plaid', '~> '
```

Autolinking should install the CocoaPods dependencies for iOS project. If it fails you can run

```bash
cd ios && bundle install && bundle exec pod install
```

##### Android Setup 

Requirements:

*   Android 5.0 (API level 21) and above.
*   Your compileSdkVersion must be 35.
*   Android gradle plugin 4.x and above.

Autolinking should handle all of the Android setup.

*   Register your Android package name in the [Dashboard](https://dashboard.plaid.com/developers/api) . This is required in order to connect to OAuth institutions (which includes most major banks).

###### Sample app 

For a sample app that demonstrates a minimal integration with the React Native Plaid Link SDK, see the [Tiny Quickstart (React Native)](https://github.com/plaid/tiny-quickstart/tree/main/react_native) .

\=\*=\*=\*=

#### Opening Link 

Before you can open Link, you need to first create a `link_token`. A `link_token` can be configured for different Link flows and is used to control much of Link's behavior. To see how to create a new `link_token`, see the API Reference entry for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . If your React Native application will be used on Android, the `link/token/create` call should include the `android_package_name` parameter. Each time you open Link, you will need to get a new `link_token` from your server.

Next, open Link via the `create` and `open` methods. These functions require version 11.6 or later of the Plaid React Native SDK.

If using a version earlier than 11.6, you must open Link with the legacy `PlaidLink` component, which configures Link and registers a callback in a single component. This approach has higher user-facing latency than using the `create` and `open` methods.

\=\*=\*=\*=

#### create 

You can initiate the Link preloading process by invoking the `create` function. After calling `create`, call `open` to open Link. This function requires SDK version 11.6 or later.

**Properties**

[linkTokenConfiguration](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-create-linkTokenConfiguration)

LinkTokenConfiguration

A configuration used to open Link with a Link Token.

[token](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-create-linkTokenConfiguration-token)

string

The `link_token` to be used to authenticate your app with Link. The `link_token` is created by calling `/link/token/create` and is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for a full list of configurations.

[noLoadingState](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-create-linkTokenConfiguration-noLoadingState)

boolean

Hides native activity indicator if true.

[logLevel](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-create-linkTokenConfiguration-logLevel)

LinkLogLevel

Set the level at which to log statements  
  

Possible values: `DEBUG`, `INFO`, `WARN`, `ERROR`

```javascript
 {
      create({token: linkToken});
      setDisabled(false);
    }
  }>
  Create Link

```

\=\*=\*=\*=

#### open 

After calling `create`, you can subsequently invoke the `open` function. Note that maximizing the delay between these two calls will reduce latency for your users by allowing Link more time to load. This function requires SDK version 11.6 or later.

**Properties**

[onSuccess](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-open-onSuccess)

LinkSuccessListener

A function that is called when a user successfully links an Item. The function should expect one argument. See [onSuccess](https://plaid.com#onsuccess) .

[onExit](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-open-onExit)

LinkExitListener

A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect one argument. See [onExit](https://plaid.com#onexit) .

[iosPresentationStyle](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-open-iosPresentationStyle)

LinkIOSPresentationStyle

The presentation style to use on iOS. Defaults to `MODAL`.  
  

Possible values: `MODAL`, `FULL_SCREEN`

[logLevel](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-open-logLevel)

LinkLogLevel

Set the level at which to log statements  
  

Possible values: `DEBUG`, `INFO`, `WARN`, `ERROR`

```javascript
 {
    const openProps = {
      onSuccess: (success: LinkSuccess) => {
      console.log(success);
      },
      onExit: (linkExit: LinkExit) => {
        console.log(exit);
      };
    open(openProps);
    setDisabled(true);
  }}>
  Open Link

```

\=\*=\*=\*=

#### PlaidLink 

PlaidLink is a React component used to open Link from a React Native application. PlaidLink renders a [Pressable](https://plaid.comhttps://reactnative.dev/docs/pressable/index.html.md) component, which wraps the component you provide and intercepts onPress events to open Link. PlaidLink is an older alternative to the `create` and `open` methods, which offer reduced Link latency and improved performance.

**Properties**

[onSuccess](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-onSuccess)

LinkSuccessListener

A function that is called when a user successfully links an Item. The function should expect one argument. See [onSuccess](https://plaid.com#onsuccess) .

[tokenConfig](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-tokenConfig)

LinkTokenConfiguration

A configuration used to open Link with a Link Token.

[token](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-tokenConfig-token)

string

The `link_token` to be used to authenticate your app with Link. The `link_token` is created by calling `/link/token/create` and is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for a full list of configurations.

[logLevel](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-tokenConfig-logLevel)

LinkLogLevel

Set the level at which to log statements  
  

Possible values: `DEBUG`, `INFO`, `WARN`, `ERROR`

[extraParams](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-tokenConfig-extraParams)

Record<string, any>

You do not need to use this field unless specifically instructed to by Plaid.

[onExit](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-onExit)

LinkExitListener

A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect one argument. See [onExit](https://plaid.com#onexit) .

[children](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-plaidlink-children)

React.ReactNode

The underlying component to render

```javascript
 {
    console.log(success);
  }}
  onExit={(exit: LinkExit) => {
    console.log(exit);
  }}
>
  Add Account

```

\=\*=\*=\*=

#### onSuccess 

The method is called when a user successfully links an Item. The onSuccess handler returns a `LinkConnection` class that includes the `public_token`, and additional Link metadata in the form of a `LinkConnectionMetadata` class.

**Properties**

[publicToken](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-publicToken)

String

Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used.

[metadata](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata)

LinkSuccessMetadata

Displayed once a user has successfully completed Link.

[accounts](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts)

Array<LinkAccount>

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](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-id)

string

The Plaid `account_id`

[name](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-name)

nullable, string

The official account name

[mask](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-mask)

nullable, 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](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-type)

LinkAccountType

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[subtype](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-subtype)

LinkAccountSubtype

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[verification\_status](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status)

nullable, LinkAccountVerificationStatus

Indicates an Item's micro-deposit-based verification or database verification status.

[pending\_automatic\_verification](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-pending-automatic-verification)

The Item is pending automatic verification

[pending\_manual\_verification](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-pending-manual-verification)

The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the deposit.

[automatically\_verified](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-automatically-verified)

The Item has successfully been automatically verified

[manually\_verified](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-manually-verified)

The Item has successfully been manually verified

[verification\_expired](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-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](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-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.

[database\_matched](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-database-matched)

The Item has successfully been verified using Plaid's data sources.

[database\_insights\_pending](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-database-insights-pending)

The Database Insights result is pending and will be available upon Auth request.

[null](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-accounts-verification-status-null)

Neither micro-deposit-based verification nor database verification are being used for the Item.

[institution](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-institution)

nullable, object

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-institution-name)

string

The full institution name, such as `'Wells Fargo'`

[id](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-institution-id)

string

The Plaid institution identifier

[linkSessionId](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-linkSessionId)

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

[metadataJson](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onsuccess-metadata-metadataJson)

nullable, Map

The data directly returned from the server with no client side changes.

```javascript
const onSuccess = (success: LinkSuccess) => {
  // If using Item-based products, exchange public_token
  // for access_token
  fetch('https://yourserver.com/exchange_public_token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.Stringify({
      publicToken: linkSuccess.publicToken,
      accounts: linkSuccess.metadata.accounts,
      institution: linkSuccess.metadata.institution,
      linkSessionId: linkSuccess.metadata.linkSessionId,
    }),
  });
};
```

\=\*=\*=\*=

#### onExit 

The `onExit` handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The `PlaidError` returned from the `onExit` handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant info in Plaid Support requests for the user.

**Properties**

[error](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-error)

LinkError

An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, `error` will be `null`.

[displayMessage](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-error-displayMessage)

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

[errorCode](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-error-errorCode)

LinkErrorCode

The particular error code. Each `errorType` has a specific set of `errorCodes`. A code of 499 indicates a client-side exception.

[errorType](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-error-errorType)

LinkErrorType

A broad categorization of the error.

[errorMessage](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-error-errorMessage)

String

A developer-friendly representation of the error code.

[errorJson](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-error-errorJson)

nullable, String

The data directly returned from the server with no client side changes.

[metadata](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata)

Map<String, Object>

An object containing information about the exit event

[linkSessionId](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-linkSessionId)

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

[institution](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-institution)

nullable, LinkInstitution

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-institution-name)

string

The full institution name, such as `'Wells Fargo'`

[id](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-institution-id)

string

The Plaid institution identifier

[status](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status)

nullable, LinkExitMetadataStatus

The point at which the user exited the Link flow. One of the following values

[requires\_questions](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-questions)

User prompted to answer security questions

[requires\_selections](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-selections)

User prompted to answer multiple choice question(s)

[requires\_recaptcha](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-recaptcha)

User prompted to solve a reCAPTCHA challenge

[requires\_code](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-code)

User prompted to provide a one-time passcode

[choose\_device](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-choose-device)

User prompted to select a device on which to receive a one-time passcode

[requires\_credentials](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-credentials)

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

[requires\_account\_selection](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-account-selection)

User prompted to select one or more financial accounts to share

[requires\_oauth](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-requires-oauth)

User prompted to enter an OAuth flow

[institution\_not\_found](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-institution-not-found)

User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.

[institution\_not\_supported](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-institution-not-supported)

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

[unknown](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-status-unknown)

An exit status that is not handled by the current version of the SDK

[requestId](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-requestId)

nullable, String

The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation

[metadataJson](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onexit-metadata-metadataJson)

nullable, Map

The data directly returned from the server with no client side changes.

```javascript
const onExit = (linkExit: LinkExit) => {
  supportHandler.report({
    error: linkExit.error,
    institution: linkExit.metadata.institution,
    linkSessionId: linkExit.metadata.linkSessionId,
    requestId: linkExitlinkExit.metadata.requestId,
    status: linkExit.metadata.status,
  });
};
```

\=\*=\*=\*=

#### onEvent 

The React Native Plaid module emits `onEvent` events throughout the account linking process. To receive these events use the `usePlaidEmitter` hook.

The `onEvent` callback is called at certain points in the Link flow. Unlike the handlers for `onSuccess` and `onExit`, the `onEvent` handler is initialized as a global lambda passed to the `Plaid` class. `OPEN`, `LAYER_READY`, and `LAYER_NOT_AVAILABLE` events will be sent immediately in real-time, and remaining events will be sent when the Link session is finished and `onSuccess` or `onExit` is called. Callback ordering is not guaranteed; `onEvent` callbacks may fire before, after, or surrounding the `onSuccess` or `onExit` callback, and event callbacks are not guaranteed to fire in the order in which they occurred. If you need the exact time when an event happened, use the `timestamp` property.  
The following `onEvent` callbacks are stable, which means that they are suitable for programmatic use in your application's logic: `OPEN`, `EXIT`, `HANDOFF`, `SELECT_INSTITUTION`, `ERROR`, `BANK_INCOME_INSIGHTS_COMPLETED`, `IDENTITY_VERIFICATION_PASS_SESSION`, `IDENTITY_VERIFICATION_FAIL_SESSION`, `LAYER_READY`, `LAYER_NOT_AVAILABLE`. The remaining callback events are informational and subject to change, and should be used for analytics and troubleshooting purposes only.

**Properties**

[eventName](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName)

LinkEventName

A string representing the event that has just occurred in the Link flow.

[AUTO\_SUBMIT\_PHONE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-AUTO-SUBMIT-PHONE)

The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid.

[BANK\_INCOME\_INSIGHTS\_COMPLETED](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-BANK-INCOME-INSIGHTS-COMPLETED)

The user has completed the Assets and Bank Income Insights flow.

[CLOSE\_OAUTH](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-CLOSE-OAUTH)

The user closed the third-party website or mobile app without completing the OAuth flow.

[CONNECT\_NEW\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-CONNECT-NEW-INSTITUTION)

The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Remember Me flow.

[ERROR](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-ERROR)

A recoverable error occurred in the Link flow, see the `error_code` metadata.

[EXIT](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-EXIT)

The user has exited without completing the Link flow and the [onExit](https://plaid.com#onexit) callback is fired.

[FAIL\_OAUTH](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-FAIL-OAUTH)

The user encountered an error while completing the third-party's OAuth login flow.

[HANDOFF](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-HANDOFF)

The user has exited Link after successfully linking an Item.

[IDENTITY\_VERIFICATION\_START\_STEP](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-START-STEP)

The user has started a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_PASS\_STEP](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-PASS-STEP)

The user has passed a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_FAIL\_STEP](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-FAIL-STEP)

The user has failed a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_PENDING\_REVIEW\_STEP](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-PENDING-REVIEW-STEP)

The user has reached the pending review state.

[IDENTITY\_VERIFICATION\_CREATE\_SESSION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-CREATE-SESSION)

The user has started a new Identity Verification session.

[IDENTITY\_VERIFICATION\_RESUME\_SESSION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-RESUME-SESSION)

The user has resumed an existing Identity Verification session.

[IDENTITY\_VERIFICATION\_PASS\_SESSION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-PASS-SESSION)

The user has passed their Identity Verification session.

[IDENTITY\_VERIFICATION\_PENDING\_REVIEW\_SESSION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-PENDING-REVIEW-SESSION)

The user has completed their Identity Verification session, which is now in a pending review state.

[IDENTITY\_VERIFICATION\_FAIL\_SESSION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-FAIL-SESSION)

The user has failed their Identity Verification session.

[IDENTITY\_VERIFICATION\_OPEN\_UI](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-OPEN-UI)

The user has opened the UI of their Identity Verification session.

[IDENTITY\_VERIFICATION\_RESUME\_UI](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-RESUME-UI)

The user has resumed the UI of their Identity Verification session.

[IDENTITY\_VERIFICATION\_CLOSE\_UI](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-IDENTITY-VERIFICATION-CLOSE-UI)

The user has closed the UI of their Identity Verification session.

[LAYER\_AUTOFILL\_NOT\_AVAILABLE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-LAYER-AUTOFILL-NOT-AVAILABLE)

The user's date of birth passed to Link is not eligible for Layer autofill.

[LAYER\_NOT\_AVAILABLE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-LAYER-NOT-AVAILABLE)

The user phone number passed to Link is not eligible for Layer.

[LAYER\_READY](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-LAYER-READY)

The user phone number passed to Link is eligible for Layer and `open()` may now be called.

[MATCHED\_SELECT\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-MATCHED-SELECT-INSTITUTION)

The user selected an institution that was presented as a matched institution. This event can be emitted if [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) is being used, if the institution was surfaced as a matched institution likely to have been linked to Plaid by a returning user, or if the institution's `routing_number` was provided when calling `/link/token/create`. For details on which scenario is triggering the event, see `metadata.matchReason`.

[OPEN](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-OPEN)

The user has opened Link.

[OPEN\_MY\_PLAID](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-OPEN-MY-PLAID)

The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.

[OPEN\_OAUTH](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-OPEN-OAUTH)

The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.

[SEARCH\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SEARCH-INSTITUTION)

The user has searched for an institution.

[SELECT\_AUTH\_TYPE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SELECT-AUTH-TYPE)

The user has chosen whether to Link instantly or manually (i.e., with micro-deposits). This event emits the `selection` metadata to indicate the user's selection.

[SELECT\_BRAND](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SELECT-BRAND)

The user selected a brand, e.g. Bank of America. The `SELECT_BRAND` event is only emitted for large financial institutions with multiple online banking portals.

[SELECT\_DEGRADED\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SELECT-DEGRADED-INSTITUTION)

The user selected an institution with a `DEGRADED` health status and was shown a corresponding message.

[SELECT\_DOWN\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SELECT-DOWN-INSTITUTION)

The user selected an institution with a `DOWN` health status and was shown a corresponding message.

[SELECT\_FILTERED\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SELECT-FILTERED-INSTITUTION)

The user selected an institution Plaid does not support all requested products for and was shown a corresponding message.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SELECT-INSTITUTION)

The user selected an institution.

[SKIP\_SUBMIT\_PHONE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SKIP-SUBMIT-PHONE)

The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Remember Me flow.

[SUBMIT\_ACCOUNT\_NUMBER](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-ACCOUNT-NUMBER)

The user has submitted an account number. This event emits the `account_number_mask` metadata to indicate the mask of the account number the user provided.

[SUBMIT\_CREDENTIALS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-CREDENTIALS)

The user has submitted credentials.

[SUBMIT\_DOCUMENTS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-DOCUMENTS)

The user is being prompted to submit documents for an Income verification flow.

[SUBMIT\_DOCUMENTS\_ERROR](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-DOCUMENTS-ERROR)

The user encountered an error when submitting documents for an Income verification flow.

[SUBMIT\_DOCUMENTS\_SUCCESS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-DOCUMENTS-SUCCESS)

The user has successfully submitted documents for an Income verification flow.

[SUBMIT\_MFA](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-MFA)

The user has submitted MFA.

[SUBMIT\_OTP](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-OTP)

The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_PHONE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-PHONE)

The user has submitted their phone number. This event is only emitted in the Link Remember Me flow.

[SUBMIT\_ROUTING\_NUMBER](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-SUBMIT-ROUTING-NUMBER)

The user has submitted a routing number. This event emits the `routing_number` metadata to indicate user's routing number.

[TRANSITION\_VIEW](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-TRANSITION-VIEW)

The `TRANSITION_VIEW` event indicates that the user has moved from one view to the next.

[VERIFY\_PHONE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-VERIFY-PHONE)

The user has successfully verified their phone number using OTP. This event is only emitted in the Link Remember Me flow.

[VIEW\_DATA\_TYPES](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-VIEW-DATA-TYPES)

The user has viewed data types on the data transparency consent pane.

[UNKNOWN](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-eventName-UNKNOWN)

The `UNKNOWN` event indicates that the event is not handled by the current version of the SDK.

[metadata](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata)

LinkEventMetadata

An object containing information about the event.

[submitAccountNumber](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-submitAccountNumber)

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

[errorCode](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-errorCode)

String

The error code that the user encountered. Emitted by: `ERROR`, `EXIT`.

[errorMessage](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-errorMessage)

String

The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.

[errorType](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-errorType)

String

The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.

[exitStatus](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-exitStatus)

String

The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`.

[institutionId](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-institutionId)

String

The ID of the selected institution. Emitted by: _all events_.

[institutionName](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-institutionName)

String

The name of the selected institution. Emitted by: _all events_.

[institutionSearchQuery](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-institutionSearchQuery)

String

The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.

[isUpdateMode](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-isUpdateMode)

String

Indicates if the current Link session is an update mode session. Emitted by: `OPEN`.

[matchReason](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-matchReason)

nullable, 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`.

[routingNumber](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-routingNumber)

Optional<String>

The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`.

[linkSessionId](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-linkSessionId)

String

The `linkSessionId` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_.

[mfaType](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-mfaType)

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

[requestId](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-requestId)

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

[selection](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-selection)

String

The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`.

[timestamp](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-timestamp)

String

An ISO 8601 representation of when the event occurred. For example, `2017-09-14T14:42:19.350Z`. Emitted by: _all events_.

[viewName](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName)

LinkEventViewName

The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`.

[ACCEPT\_TOS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-ACCEPT-TOS)

The view showing Terms of Service in the identity verification flow.

[CONNECTED](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-CONNECTED)

The user has connected their account.

[CONSENT](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-CONSENT)

We ask the user to consent to the privacy policy.

[CREDENTIAL](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-CREDENTIAL)

Asking the user for their account credentials.

[DOCUMENTARY\_VERIFICATION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-DOCUMENTARY-VERIFICATION)

The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).

[ERROR](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-ERROR)

An error has occurred.

[EXIT](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-EXIT)

Confirming if the user wishes to close Link.

[INSTANT\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-INSTANT-MICRODEPOSIT-AUTHORIZED)

The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.

[KYC\_CHECK](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-KYC-CHECK)

The view representing the "know your customer" step in the identity verification flow.

[LOADING](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-LOADING)

Link is making a request to our servers.

[MFA](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-MFA)

The user is asked by the institution for additional MFA authentication.

[NUMBERS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-NUMBERS)

The user is asked to insert their account and routing numbers.

[NUMBERS\_SELECT\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-NUMBERS-SELECT-INSTITUTION)

The user goes through the Same Day micro-deposits flow with Reroute to Credentials.

[OAUTH](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-OAUTH)

The user is informed they will authenticate with the financial institution via OAuth.

[PROFILE\_DATA\_REVIEW](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-PROFILE-DATA-REVIEW)

The user is asked to review their profile data in the Layer flow.

[RECAPTCHA](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-RECAPTCHA)

The user was presented with a Google reCAPTCHA to verify they are human.

[RISK\_CHECK](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-RISK-CHECK)

The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).

[SAME\_DAY\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SAME-DAY-MICRODEPOSIT-AUTHORIZED)

The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.

[SCREENING](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SCREENING)

The watchlist screening step in the identity verification flow.

[SELECT\_ACCOUNT](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELECT-ACCOUNT)

We ask the user to choose an account.

[SELECT\_AUTH\_TYPE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELECT-AUTH-TYPE)

The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).

[SELECT\_BRAND](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELECT-BRAND)

The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELECT-INSTITUTION)

We ask the user to choose their institution.

[SELECT\_SAVED\_ACCOUNT](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELECT-SAVED-ACCOUNT)

The user is asked to select their saved accounts and/or new accounts for linking in the Link Remember Me flow.

[SELECT\_SAVED\_INSTITUTION](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELECT-SAVED-INSTITUTION)

The user is asked to pick a saved institution or link a new one in the Link Remember Me flow.

[SELFIE\_CHECK](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SELFIE-CHECK)

The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.

[SUBMIT\_PHONE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-SUBMIT-PHONE)

The user is asked for their phone number in the Link Remember Me flow.

[UPLOAD\_DOCUMENTS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-UPLOAD-DOCUMENTS)

The user is asked to upload documents (for Income verification).

[VERIFY\_PHONE](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-VERIFY-PHONE)

The user is asked to verify their phone OTP in the Link Remember Me flow.

[VERIFY\_SMS](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-onevent-metadata-viewName-VERIFY-SMS)

The SMS verification step in the identity verification flow.

```javascript
usePlaidEmitter((event) => {
  console.log(event);
});
```

\=\*=\*=\*=

#### submit 

The `submit` function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number).

**Properties**

[submissionData](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-submit-submissionData)

object

Data to submit during a Link session.

[phoneNumber](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-submit-submissionData-phoneNumber)

String

The end user's phone number.

[dateOfBirth](https://plaid.com/docs/link/react-native/index.html.md#link-react_native-submit-submissionData-dateOfBirth)

String

The end user's date of birth. To be provided in the format "yyyy-mm-dd".

```javascript
submit({
  "phone_number": "+14155550123"
})
```

\=\*=\*=\*=

#### destroy 

The `destroy` function clears state and resources from a previously opened session. The `destroy` function is only available on Android, as this state clearing behavior occurs automatically on iOS. `destroy` is intended for use with the Layer product and should be used if you are making multiple calls to `create` before calling `submit`. By calling `destroy` between the `create` calls, you can avoid unexpected behavior on the `submit` call.

```javascript
create(tokenConfiguration1)
async () => {
  try {
    await destroy(); // Clear previous session state
    create(tokenConfiguration2);
    submit(phoneNumber);
  } catch (e) {
    console.error('Error during flow:', e);
  }
}
```

\=\*=\*=\*=

#### OAuth 

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md) .

\=\*=\*=\*=

#### Upgrading 

The latest version of the SDK is available from [GitHub](https://github.com/plaid/react-native-plaid-link-sdk) . New versions of the SDK are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application.

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

##### Migration guides 

*   Version 12.x removes the `PlaidLink` component and `openLink` function, which were deprecated in version 11.6.0. If you are using this method of opening Link, replace it with the new process that uses `create` and then `open`. For details, see [Opening Link](https://plaid.com/docs/link/react-native/index.html.md#opening-link) or the [README](https://github.com/plaid/react-native-plaid-link-sdk?tab=readme-ov-file#version--1160) . Version 12.x also removes the `PROFILE_ELIGIBILITY_CHECK_ERROR`.
*   Version 12.x updates the Android target SDK version and compile version from 33 to 35 and requires use of an Xcode 16 toolchain.
*   Version 11.x contains several breaking changes from previous major versions. For details, see the [migration guide on GitHub](https://github.com/plaid/react-native-plaid-link-sdk/blob/master/v11-migration-guide.md) .
*   When upgrading from 9.x to 10.x or later, you should remove any invocation of `useDeepLinkRedirector` on iOS, as it has been removed from the SDK, since it is no longer required for handling Universal Links. You must make sure you are using a compatible version of React Native (0.66.0 or higher) and the Plaid iOS SDK (see the [version compatibility chart](https://github.com/plaid/react-native-plaid-link-sdk#version-compatibility) on GitHub).
*   No code changes are required to upgrade from 8.x to 9.x, although you must make sure you are using a compatible version of the Plaid iOS SDK (4.1.0 or higher).
*   The only difference between version 7.x and 8.x is that 8.x adds support for Xcode 14. No code changes are required to upgrade from 7.x to 8.x, although you must convert to an Xcode 14 toolchain.

---


# Link - Returning user experience | Plaid Docs

The returning user experience 
==============================

#### Learn how Plaid streamlines the user experience for returning users 

#### Overview 

##### The returning user experience for a saved user 

The user starts a Link session.

(An image of "The user starts a Link session.")

(An image of "They enter their phone number.")

(An image of "Plaid recognizes this number as one that's connected to Plaid before, and asks the user to confirm a code sent by SMS.")

(An image of "The user can then instantly connect to an institution that they've previously connected to with Plaid.")

(An image of "They can also choose which saved accounts to connect to your app.")

The returning user experience (formerly known as Remember Me) streamlines onboarding for users who have already connected a financial account with Plaid in the US or Canada. In Link, users can choose to associate their phone number with the accounts they're connecting to a financial app or service. Once users have opted-in to being 'remembered' by Plaid, they'll be able to quickly connect those same accounts to other financial apps and services in the future using a one-time password for thousands of financial institutions, resulting in higher conversion and a simpler user experience.

After the Consent screen in Link, users can input their phone number and verify it using a one-time password sent to their device. Next, the user will proceed to select an institution and connect their account(s). Once account verification is completed, Plaid will associate the institution and accounts with the user's phone number.

This experience is automatically enabled for all eligible customers, and you do not need to make any updates to your integration to support it.

The legacy returning user experience flows (Institution Boosting, Pre-Matched RUX, and Pre-Authenticated RUX) have been replaced by the revamped returning user experience (formerly known as the Remember Me flow) as of October 28, 2024. For questions or more details, contact your Plaid Account Manager.

##### The returning user experience for a new user 

The user starts a Link session.

(An image of "The user starts a Link session.")

(An image of "They enter their phone number.")

(An image of "Plaid does not recognize this number as one that's connected to Plaid before, but the user is still prompted to confirm their number through an SMS code.")

(An image of "The user selects an institution to connect with.")

(An image of "They enter their credentials, or proceed through an OAuth flow.")

(An image of "...and they select their account.")

(An image of "This user has successfully connected to this institution, and it's now available for them to connect to the next time they start the returning user experience.")

##### Returning user experience 

When users want to connect their saved institutions and accounts to additional Plaid-powered apps or services, Plaid runs security checks to detect that they are a returning user with the same phone number and device.

Users can choose to be remembered by Plaid, making future connections faster and easier. To enroll, the user will enter their phone number in Link. This flow is available for phone numbers with country codes +1 (covering the United States, Canada, and part of the Caribbean), +44 (UK), and +52 (Mexico); users selecting codes from any other country will be redirected to the standard Link flow. The default country shown in the dropdown will be based on the country code(s) provided in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call; for example, if [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is called with a single country code, that country will be shown as the default; if it is called with multiple countries, including `US`, the United States will be shown as the default.

Supported institutions that users have previously connected an account from and offer a streamlined experience will be designated by the lightning bolt in the institution selection pane. If an institution does not have a lightning bolt, users will be required to go through the full Link experience to connect their account.

#### Pre-filling phone numbers for faster account verification 

Link sessions can be enabled for a more streamlined user experience when Plaid already knows the user’s phone number. When a `user.phone_number` is provided via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , Plaid will pre-fill the phone number in Link for the user. Only the last 4 digits of the associated phone number are shown in order to preserve user privacy.

The user can then verify their phone number using a one-time password. Plaid will deploy a number of security checks to verify that the phone number belongs to the device before the user can select which saved institution to connect to an app or service. Pre-filling phone numbers can help boost conversion while reducing the number of manual inputs from users.

#### Passkeys 

Passkeys are a secure alternative to passwords and can provide a streamlined account linking experience for thousands of institutions. Plaid will automatically enable passkeys for Link sessions on iOS devices when you use the Plaid iOS SDK 4.3.0+ or React Native 10.2.0+ SDK.

In Link, users will be prompted to enable passkeys with Face or Touch ID before proceeding with connecting their financial accounts to a chosen app or service. When the same user wants to connect to another app or service, they can use their passkey with Face or Touch ID instead of a one-time password for a streamlined authentication experience.

(An image of "Plaid passkey flow for returning users: Connect with customer app, input phone, log in with Face/Touch ID, select saved account.")

#### Passport 

Passport provides a streamlined experience where end users can opt-in to saving their financial account connections and personal information in a Plaid account. They can then securely and easily share this account with some Plaid-powered apps and services.

Passport is available now for [Consumer Report by Plaid Check](https://plaid.com/docs/check/index.html.md) . End users can use Passport to share their consumer report with Plaid Check customers and partners to receive credit-related services. This experience is automatically enabled for eligible customers, and you do not need to make any updates to your integration to support it.

To view the Passport experience, you can launch Link with any [Plaid Check](https://plaid.com/docs/check/index.html.md) product in the Sandbox environment.

#### Silent Network Authentication 

Silent Network Authentication (SNA) is an aspect of the mobile returning user experience that enables Plaid to verify a consumer's phone number using their mobile network carrier. Eligible users can skip manual OTP verification of their phone number, which removes one step in the Link flow. SNA is currently used for Layer and for the returning user experience within Plaid Check Consumer Reports, and will be rolled out to all eligible Plaid Check sessions by the end of May 2025. SNA is also occasionally used for eligible returning user experience flows for other products.

SNA is supported on mobile flows using Plaid's native or React Native mobile SDKs using Android SDK version >=5.6.0 and iOS SDK version >=4.7. Customers using Layer or Plaid Check Consumer Reports are strongly recommended to upgrade to iOS SDK version >=6.0.1 (or React Native iOS >=12.0.2) in order to take advantage of substantial performance improvements to the SNA flow. Aside from using a compatible SDK, no work is required on your part to enable SNA.

SNA is compatible with AT&T, T-Mobile, and Verizon, and works by verifying the user's SIM is connected to the mobile network carrier and not spoofed or cloned. If SNA cannot verify the user's number (for example, because verification failed, their network is not compatible, or mobile data is unavailable) Plaid will fall back to the manual OTP flow.

SNA is available only in Production and cannot currently be emulated in Sandbox.

#### Testing in Sandbox 

The returning user flow can be tested in the Sandbox or Production environments.

Real phone numbers do not work in Sandbox. Instead, Sandbox has been seeded with a test user whose phone numbers may be used to trigger different scenarios. To explore each scenario, enter the corresponding phone number and correct OTP. For all scenarios, the correct OTP is `123456`.

Returning User: A user who has previously enrolled in the returning user experience by confirming their device and successfully linking an Item.

| Link Returning User Sandbox Scenarios | Seeded Phone Number |
| --- | --- |
| New User | `415-555-0010` |
| Verified Returning User | `415-555-0011` |
| Verified Returning User: linked new account | `415-555-0012` |
| Verified Returning User: linked OAuth institution | `415-555-0013` |
| Verified Returning User + new device | `415-555-0014` |
| Verified Returning User: automatic account selection | `415-555-0015` |

#### Tracking events 

Link emits events to indicate whether or not users opt-in to being remembered by Plaid:

##### Events 

| Event | Meaning |
| --- | --- |
| `SUBMIT_PHONE` | User has provided their phone number to be remembered by Plaid |
| `SUBMIT_OTP` | User has entered an OTP code to verify their phone number |
| `VERIFY_PHONE` | User has successfully verified their phone number |
| `SKIP_SUBMIT_PHONE` | User chose not provide their phone number to be remembered by Plaid |
| `CONNECT_NEW_INSTITUTION` | User chose to connect a new institution |

##### View names 

The following can be found in the `view_name` field in the `TRANSITION_VIEW` event for returning user panes:

| View name | Meaning |
| --- | --- |
| `SUBMIT_PHONE` | User was prompted to provide their phone number to be remembered by Plaid |
| `VERIFY_PHONE` | User was prompted to verify their phone number |
| `SELECT_SAVED_ACCOUNT` | User was prompted to select the underlying account from the saved Item |
| `SELECT_SAVED_INSTITUTION` | User was prompted to select one of multiple saved Items |

##### Match reasons 

The `match_reason` field in the `SELECT_INSTITUTION` event has the following values for the returning user flow:

| Match reason | Meaning |
| --- | --- |
| `AUTO_SELECT_SAVED_INSTITUTION` | The `SELECT_SAVED_INSTITUTION` pane was skipped |
| `SAVED_INSTITUTION` | User selected a saved institution |
| `SAVED_ACCOUNT` | User selected a saved account |

##### Error events 

Link will emit the `ERROR` event when the user submits an invalid phone number or an invalid OTP. The `error_code` will be `INVALID_PHONE_NUMBER` or `INVALID_OTP`, respectively.

For more details, see [Link SDK documentation](https://plaid.com/docs/link/web/index.html.md) . For more information on tracking Link conversion in general, see [Improving Link conversion](https://plaid.com/docs/link/best-practices/index.html.md#improving-link-conversion) .

---


# Link - Troubleshooting | Plaid Docs

Link errors and troubleshooting 
================================

#### Errors in the Link flow 

#### Link error codes 

Any errors during Link will be returned via the Link flow; for details, see the guide for your specific platform. Since any failed user attempt to log on to a financial institution for any reason, even an incorrect password, will result in a Link error, you should expect to see the occasional error during Link. In most cases, Link will guide your user through the steps required to resolve the error.

The most common case in which you will need a special flow for Link errors is the `ITEM_LOGIN_REQUIRED` error. For instructions on handling this error, see [Update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

For more details, or if you need to troubleshoot a problem involving an error message from the API, see [Item errors](https://plaid.com/docs/errors/item/index.html.md) .

#### Missing institutions or "Connectivity not supported" error 

##### Symptom 

*   Your user cannot find their financial institution in Link, even though it is one of the 11,500+ institutions supported by Plaid.
*   Your user experiences a "Connectivity not supported" error message after selecting their institution in Link.

##### Common causes 

*   The institution does not support one of the products specified in Link initialization.
*   The institution is associated with a country not specified in Link initialization.
*   The institution is associated with a country your Plaid account hasn't been enabled for.

##### Troubleshooting steps 

#### Institution unhealthy 

##### Symptom 

When a user tries to connect their account, they receive a message in Link that Plaid may be experiencing connectivity issues to that institution. For more details, see [Institution status in Link](https://plaid.com/docs/link/institution-status/index.html.md) .

##### Common causes 

*   Plaid's connection to the institution is down or degraded.

##### Troubleshooting steps 

#### Duplicate Items 

##### Symptom 

Your user has multiple Items that seem to represent the same underlying set of accounts.

##### Common causes 

*   The user added the same Item more than once.

##### Troubleshooting steps 

#### Missing accounts 

##### Symptom 

Some of the end users' accounts are not present in the Item, or a new account added by the user does not appear in the Item.

##### Common causes 

*   The user linked their account but did not grant your app permission to access the account, or created the account after linking the Item and did not grant your app permission to access newly created accounts.
*   The account is not compatible with settings specified during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. For example, if `auth` was one of the required products specified when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , accounts that do not support Auth, such as credit card accounts, will not appear on the Item.

##### Troubleshooting steps 

#### Link flow is failing 

##### Symptom 

The Link flow is not working correctly for the user -- the `onSuccess` callback may not be sent, Link may not load, or redirects may not function correctly.

##### Common causes 

*   Third party software, such as ad-blocking browser extensions, may be interfering with Link.
*   The end user linked their account via an OAuth flow and OAuth is not configured correctly.

##### Troubleshooting steps 

#### "You may need to update your app", "Couldn't connect to your institution", or "Something went wrong" error message 

##### Symptom 

After selecting a bank in Link, the user gets an error message saying "You may need to update your app in order to connect to Chase" (or another institution), "Couldn't connect to your institution", or "Something went wrong". This happens only in Production.

##### Common causes 

*   You haven't selected a use case for Link.
*   The full list of OAuth prerequisites have not been completed to enable your client id for a given institution's OAuth connection.

##### Troubleshooting steps 

#### Interactive Brokers customer prompted to enter a query id and token 

##### Symptom 

When linking an Interactive Brokers account, the end user is prompted to enter a "token" and/or "query id" but does not know where or how to get one.

##### Common causes 

This is part of the standard Interactive Brokers Link flow. Interactive Brokers requires this step for any customer linking a third party service, such as Plaid, to their account.

###### Troubleshooting steps 

#### OAuth not working 

First, verify these settings before reviewing the more detailed OAuth troubleshooting guides below:

If none of the steps above resolve your problem, see the specific OAuth troubleshooting guides below. If you do not see your problem listed, or following the guide does not fix the problem, [contact Support](https://dashboard.plaid.com/support/new/product-and-development/developer-lifecycle/sdk) .

#### OAuth institutions not appearing in Link 

##### Symptom 

Institutions that use OAuth, such as Capital One or Wells Fargo, are not appearing in the Link UI.

##### Common causes 

*   A `redirect_uri` or `android_package_name` was not specified in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   The redirect URI or Android package name was not allowlisted on the [Plaid Dashboard](https://dashboard.plaid.com/developers/api) .

##### Troubleshooting steps 

#### OAuth flow shows unsupported browser warning 

##### Symptom 

Upon entering their institution's OAuth flow, users see a warning that their browser is not supported.

##### Common causes 

*   The Plaid integration is using a webview with an incorrectly configured user agent.

##### Troubleshooting steps 

#### OAuth redirects not working 

##### Symptom 

Users are not being redirected back to Link after completing their institution's OAuth flow.

##### Common causes 

###### Android 

*   An `android_package_name` was not specified in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .
*   An incorrect `android_package_name` was specified in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

###### iOS 

*   Universal Links are not correctly configured.

##### Troubleshooting steps 

###### Android 

###### iOS 

#### "Current version not supported" or PUBLIC\_KEY\_NOT\_ENABLED 

##### Symptom 

*   Link displays a "Current version not supported" message on launch, or you see a `PUBLIC_KEY_NOT_ENABLED` error on the backend.

##### Common causes 

*   The integration is using a public key to launch Link instead of a Link token. As of February 2025, public key integrations are no longer allowed.

##### Troubleshooting steps

---


# Link - Update mode | Plaid Docs

Updating Items via Link 
========================

#### Use update mode to add permissions to Items, or to resolve ITEM\_LOGIN\_REQUIRED status 

(An image of "Plaid Link update mode: Connect account, enter credentials, select account, and see success confirmation screen.")

#### When to use update mode 

Update mode refers to any Link session launched for an Item after that Item's initial creation. Update mode is used when an existing Item requires input from a user, such as to update credentials or to grant additional consent.

One common use of update mode is to update authentication or authorization for an Item. This can be required when access to an existing Item stops working: for example, if the end user changes a password on an Item that does not use an OAuth connection, or if authorization for the Item has expired. Update mode can also be used pre-emptively to renew authorization for an Item.

Update mode can also be used to request permissions that the user did not originally grant during the initial Link flow. This can include specific OAuth permissions, access to new accounts, or additional product scopes or use cases. Update mode can be used to manage [permissions granted via OAuth](https://plaid.com/docs/link/oauth/index.html.md#scoped-consent) , as well as permissions granted directly through Plaid via [Account Select](https://plaid.com/docs/link/customization/index.html.md#account-select) or [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . When used to request additional permissions, Plaid will show a streamlined Link experience in update mode. For example, if a user is being asked to add a new product, they may not need to log in to their financial institution.

For some older Items created before March 2023, data for all accounts may be available, even if the user did not select the account in Account Select, and access to new accounts may be granted without needing to use the update mode flow. If these Items are at OAuth institutions, they will be updated to use the current Account Select behavior when they are sent through update mode. For more details, see [Account Select](https://plaid.com/docs/link/customization/index.html.md#account-select) .

Update mode is also used to launch feature-specific flows that require returning to Link. For example, update mode is used for confirming the micro-deposit verification code in the [Same-Day Micro-Deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) Auth flow or to collect statement copies when using [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) . For details on using update mode with these flows, see the product-specific pages.

##### Resolving ITEM\_LOGIN\_REQUIRED, PENDING\_EXPIRATION, or PENDING\_DISCONNECT 

Receiving an [ITEM\_LOGIN\_REQUIRED](https://plaid.com/docs/errors/item/index.html.md#item_login_required) error or a [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) or [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_expiration) webhook indicates that the Item should be re-initialized via update mode.

If you receive the `ITEM_LOGIN_REQUIRED` error after calling a Plaid endpoint, implement Link in update mode during the user flow, and ask the user to re-authenticate before proceeding to the next step in your flow.

If you receive the `ITEM_LOGIN_REQUIRED` error via the [ITEM: ERROR](https://plaid.com/docs/api/items/index.html.md#error) webhook, or if you receive either the [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) or [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) webhook, re-authenticate with Link in update mode when the user is next in your app. You will need to tell your user (using in-app messaging and/or notifications such as email or text message) to return to your app to fix their Item.

When resolving these issues, for most institutions, Plaid will present an abbreviated re-authentication flow requesting only the minimum user input required to repair the Item. For example, if the Item entered an error state because the user's OTP token expired, the user may be prompted to provide another OTP token, but not to fully re-login to the institution.

Self-healing Item notifications

If a user has connected the same account via Plaid to multiple different apps, resolving the `ITEM_LOGIN_REQUIRED` error for an Item in one app may also fix Items in other apps. If one of your Items is fixed in this way, Plaid will notify you via the [LOGIN\_REPAIRED](https://plaid.com/docs/api/items/index.html.md#login_repaired) webhook. Upon receiving this webhook, you can dismiss any messaging you are presenting to the user telling them to fix their Item via update mode.

##### Requesting additional products, accounts, permissions, or use cases 

You can use update mode to request your users to share new accounts with you. Receiving a [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhook indicates that Plaid has detected new accounts that you may want to ask your users to share. For more details, see [Using update mode to request new accounts](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) .

Update mode is required when adding Assets, Statements, Income, or Plaid Check Consumer Report to an existing Item. For details, see [Adding credit products](https://plaid.com/docs/link/update-mode/index.html.md#adding-credit-products) .

For Items enabled for Data Transparency Messaging, update mode is required to add additional product and use case consents. For more details, see the [Data Transparency Messaging](https://plaid.com/docs/link/update-mode/index.html.md#data-transparency-messaging) section of this page.

Update mode can optionally be used for resolving errors when adding Auth or Identity; for more details, see [Resolving ACCESS\_NOT\_GRANTED or NO\_AUTH\_ACCOUNTS errors via product validations](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) .

Update mode can be used to request OAuth permissions: triggering update mode for an OAuth institution will cause the user to re-enter the OAuth flow, where they can then grant any required OAuth permissions they failed to grant originally, or restore OAuth permissions they may have revoked. The update mode flow for OAuth institutions will also contain guidance recommending which permissions the user should grant: for more details, see the [OAuth documentation](https://plaid.com/docs/link/oauth/index.html.md#scoped-consent) .

When an Item is sent through update mode, users can also choose to revoke access they had previously granted. If you lose access to necessary accounts or OAuth permissions after the user completes the update mode flow, you may need to send the user through update mode again. For more details, see [Managing consent revocation](https://plaid.com/docs/link/oauth/index.html.md#managing-consent-revocation) . To prevent users from revoking access to the Auth or Identity products, you can also use [Update Mode with Product Validations](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) .

##### Refreshing Item expiration dates 

[Certain institutions](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) enforce expiration dates on Item consent. You can find an Item's consent expiration date by calling [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) and checking the `consent_expiration_time` value in the response.

If an Item has an expiration date, update mode can be used to renew consent on that Item. Whenever an Item is successfully sent through update mode, the Item consent expiration date will be updated as though the Item were newly created.

Seven days before an Item's consent expires, you will receive a [PENDING\_DISCONNECT (US/CA) or PENDING\_EXPIRATION (UK/EU) webhook](https://plaid.com/docs/link/update-mode/index.html.md#resolving-item_login_required-pending_expiration-or-pending_disconnect) to notify you to launch update mode. However, you do not need to wait for this webhook in order to refresh the Item.

#### Using update mode 

##### With an access token 

To use update mode for an Item, initialize Link with a `link_token` configured with the `access_token` for the Item that you wish to update.

##### With a user token 

To use update mode for a user, initialize Link with a `link_token` configured with the `user_token` for the user whose items you wish to update and the [update.user](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-update-user) field set to `true`. This is the only way to use update mode if you are using [Plaid Check](https://plaid.com/docs/check/index.html.md) products. In Link, the user will be prompted to repair the broken Item. If there are multiple Items in need of repair, the user will be prompted to fix the most recently broken Item. To repair all items associated with a user, you will need to send the user through Link once for each broken Item (you can reuse the same Link token). You can retrieve the status of all Items associated with a user by calling the [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) endpoint.

##### With a transfer authorization id 

To use update mode for a Transfer authorization with `USER_ACTION_REQUIRED` as the decision rationale code, initialize Link with a `link_token` configured with `transfer.authorization_id` set for the authorization that you wish to update; no access token is required. For more details, see the [Transfer documentation](https://plaid.com/docs/transfer/creating-transfers/index.html.md#repairing-items-in-item_login_required-state) .

##### Sample code 

No products should be added to the `products` array and no product-specific request parameters should be specified when creating a `link_token` for update mode, unless you are using update mode to [add Assets, Statements, Income, or Plaid Check Consumer Report](https://plaid.com/docs/link/update-mode/index.html.md#adding-credit-products) , or if you are using Auth and/or Identity and wish to use the beta [Update Mode with Product Validations flow](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) . If you are using update mode to [add consented products](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) , the products must be added to the `additional_consented_products` array instead.

You can obtain a `link_token` using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint.

If your integration uses redirect URIs normally, create the Link token with a redirect URI, as described in [Configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
// Create a one-time use link_token for the Item.
// This link_token can be used to initialize Link
// in update mode for the user
const configs = {
  user: {
    client_user_id: 'UNIQUE_USER_ID',
  },
  client_name: 'Your App Name Here',
  country_codes: [CountryCode.Us],
  language: 'en',
  webhook: 'https://webhook.sample.com',
  redirect_uri: "https://www.sample.com/redirect.html",
  access_token: 'ENTER_YOUR_ACCESS_TOKEN_HERE',
};
app.post('/create_link_token', async (request, response, next) => {
  const linkTokenResponse = await client.linkTokenCreate(configs);


  // Use the link_token to initialize Link
  response.json({ link_token: linkTokenResponse.data.link_token });
});
```

Link auto-detects the appropriate institution and handles the credential and multi-factor authentication process, if needed.

An Item's `access_token` does not change when using Link in update mode, so there is no need to repeat the exchange token process. Likewise, a User's `user_token` does not change when using Link in update mode, so there is no need to create a new `user_token`.

```javascript
// Initialize Link with the token parameter
// set to the generated link_token for the Item
const linkHandler = Plaid.create({
  token: 'GENERATED_LINK_TOKEN',
  onSuccess: (public_token, metadata) => {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: (err, metadata) => {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  },
});
```

When an Item is restored from the `ITEM_LOGIN_REQUIRED` state via update mode, if it has been initialized with a product that sends Item webhooks (such as Transactions or Investments), the next webhook fired for the Item will include data for all missed information back to the last time Plaid made a successful connection to the Item.

If the Item has been initialized with Transactions, and was in an error state for over 24 hours, Plaid will check for new transactions immediately after update mode is complete.

##### Using update mode to request new accounts 

The use of update mode to select new accounts is not available for end user financial institution accounts in the UK or EU. In those regions, delete the old Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and create a new one instead.

You can allow end users to [add new accounts](https://plaid.com/docs/link/update-mode/index.html.md#account-selection-screens-in-update-mode) to an Item by enabling Account Select when initializing Link in update mode. To do so, first initialize Link for update mode by creating a `link_token` using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint, passing in the `access_token` and other parameters as you normally would in update mode.

In addition, make sure you specify the following:

1.  The `update.account_selection_enabled` flag set to `true`.
    
2.  (Optional) A `link_customization_name`. The settings on this customization will determine which View Behavior for the [Account Select pane](https://plaid.com/docs/link/customization/index.html.md#account-select) is shown in the update mode flow.
    
3.  (Optional) Any `account_filters` to specify [account filtering](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-account-filters) . Note that this field can only be set for update mode if `update.account_selection_enabled` is set to `true`.
    

Once your user has updated their account selection, all selected accounts will be shared in the [accounts](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts) field in the [onSuccess()](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback from Link. Any de-selected accounts will no longer be shared with you. You will only be able to receive data for these accounts the user selects in update mode going forward.

Adding an account through update mode will cause Plaid to fetch data for the newly added account. However, [recurring transactions](https://plaid.com/docs/transactions/index.html.md#recurring-transactions) streams will not be calculated for the new account until either the next periodic transactions update for the Item occurs or the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint is called.

This update mode flow can also be used to remove accounts from an Item. We recommend that you remove any data associated with accounts that your user has de-selected. Note that Chase is an exception to the ability to remove accounts via update mode; to remove access to a specific account on a Chase Item, the end user must do so through the online Chase Security Center.

```bash
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "client_name": "My App",
  "user": { "client_user_id": "${UNIQUE_USER_ID}" },
  "country_codes": ["US"],
  "language": "en",
  "webhook": "https://webhook.sample.com",
  "access_token": "${ACCESS_TOKEN}",
  "link_customization_name": "account_selection_v2_customization",
  "redirect_uri": "https://www.sample.com/redirect.html",
  "update": { "account_selection_enabled": true }
}'
```

When using the Assets product specifically, if a user selects additional accounts during update mode but does not successfully complete the Link flow, Assets authorization will be revoked from the Item. If this occurs, have the user go through a new Link flow in order to generate an Asset Report, or, if you have Data Transparency Messaging enabled, use update mode to re-authorize the Item for assets, as described in the next section.

If the Item is initialized with Auth or Transfer, then at certain OAuth institutions, the end user may not be given the option to select non-depository accounts in the Update Mode flow. If you need to add accounts that are not compatible with Auth (for example, because you are adding a new product to the Item), contact your Plaid Account Manager to request that the "skip adding account filters in Update Mode" option be enabled for your account.

If you are using update mode to add a debitable checking or savings account in response to a `NO_AUTH_ACCOUNTS` error, see [Resolving ACCESS\_NOT\_GRANTED or NO\_AUTH\_ACCOUNTS errors via product validations](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) for a better method to resolve this error.

##### Resolving ACCESS\_NOT\_GRANTED or NO\_AUTH\_ACCOUNTS errors via Product Validations 

To request access to Update Mode with Product Validations, contact support or your Plaid account manager. If you attempt to use this flow before being granted access, the update mode flow will work, but the product validations will not be applied.

The Auth and Identity products can be added to an Item post-Link, by calling an Auth or Identity related endpoint, rather than including `auth` or `identity` in the products array. However, if the user did not share the necessary permissions or accounts to support these products, the Item will return an `ACCESS_NOT_GRANTED` or `NO_AUTH_ACCOUNTS` error. Update Mode with Product Validations (UMPV) applies product-specific validations to the selections a user makes in the update mode flow, resulting in higher conversion than resolving these errors via regular update mode.

The process to use UMPV is the same as described in [Using update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode) , except that you will also include the `products` array in the request with the value `auth` and/or `identity` for the product(s) you wish to validate. You must use the `products` array with UMPV; including `auth` or `identity` in other fields such as `required_if_supported_products` or `optional_products` will not activate UMPV.

UMPV will enforce the same level of product validation as is normally used on an initial Link attempt: the user will be instructed on which permissions to grant, and if they do not make these selections, they will be prompted to go back through the flow. In the case of `NO_AUTH_ACCOUNTS`, the account selection flow will also be automatically enabled if necessary.

UMPV can also be used preventatively, to prevent users in the update mode flow from accidentally removing permissions they have already granted. Applying UMPV to any update mode session for an Auth- or Identity-enabled Item will prompt users to fix their selections if they remove the accounts or permissions required for these products.

UMPV can only be used for `auth` or `identity`. It is also not compatible with [Adding credit products](https://plaid.com/docs/link/update-mode/index.html.md#adding-credit-products) ; the two cannot be used in a single update mode flow, although they can be used on the same Item, via separate update mode sessions.

##### Adding credit products 

Credit products (Assets, Statements, Income, and Plaid Check Consumer Report) have unique consent flows in Link. To add one of these products to an Item that did not previously have it enabled, you will need to send the user through update mode so that they can go through the product-specific consent flow before the product is added to the Item.

The process to do this is the same as described in [Using update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode) , except that in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, you will also include the `products` array in the request with the value for the product you wish to add, such as `assets`, `statements`, `income_verification`, `cra_base_report`, etc. You will also need to add any required product-specific fields -- for example, if adding `statements`, you will need to add the `statements` configuration object, or if adding Consumer Report, you will need to call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and include the `user_token`. For examples and details, see the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) documentation.

If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the consent panes. Otherwise, they will be prompted to complete the full flow.

#### Data Transparency Messaging 

For Items that are enabled for [Data Transparency Messaging (DTM)](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) , update mode is required for any of the following: requesting additional consented products, requesting additional consented use cases, or renewing consent.

##### Requesting additional consented products 

For Items with [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) enabled, you need user consent to access new products. To do so, initialize Link for update mode by creating a `link_token` using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint and passing in the `access_token`. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in [Configure your Link token with your redirect URI](https://plaid.com/docs/link/oauth/index.html.md#configure-your-link-token-with-your-redirect-uri) .

In addition, make sure you specify the following when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to add an additional consented product in update mode:

*   The `additional_consented_products` field should be set to include **any new products you want to gather consent for.**
    *   For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in `identity` to the `additional_consented_products` field.
    *   To see the currently authorized and consented products on an Item, use the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) endpoint.
*   The `link_customization_name` should be set to a customization with Data Transparency Messaging enabled. The use case string should also be broadened to include your reasons for accessing the new data. If the use case is not customized, the default use case will be present on the Data Transparency Messaging pane.

If the upgrade was successful, you will receive the `onSuccess()` callback and you will have access to the API endpoints for all of the products you passed into Link update mode. The new products will only be billed once the related API endpoints are called, even if they would otherwise be billed upon Item initialization (e.g., Transactions).

When using update mode to add product consent for an Item with DTM enabled, you must use the `additional_consented_products` parameter, not the `products` parameter, unless you are adding [Assets, Statements, Income, or Plaid Check Consumer Report](https://plaid.com/docs/link/update-mode/index.html.md#adding-credit-products) or using [Product Validations (beta)](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) .

##### Requesting additional use cases 

For Items with DTM enabled, your user will be prompted to consent to their data being used for specific use cases, not just specific products. If you need to obtain consent for additional use cases, you can update your Link customization to add the use cases, then send your user through update mode.

#### Update mode and Layer 

During the [Layer](https://plaid.com/docs/layer/index.html.md) flow, if the end user has an Item in an unhealthy state that requires update mode, this Item will still be surfaced in Link. If the user chooses to share this Item via Layer, they will automatically be sent through update mode as part of the Layer flow.

#### Update mode at PNC with Auth 

When using Update mode with Auth for Items at PNC, the Item's account and routing number may need to be refreshed after the update mode flow is complete. It's recommended to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) (or [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) ) after completing update mode for these Items. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) . This issue only impacts PNC Items used with the Auth product; you do not need to do this for Items at other institutions or when using products other than Auth.

#### Testing update mode 

Update mode can be tested in the Sandbox using the [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) endpoint, which will force a given Item into an `ITEM_LOGIN_REQUIRED` state.

#### Example React code in Plaid Pattern 

For a real-life example that illustrates the handling of update mode, see [linkTokens.js](https://github.com/plaid/pattern/blob/master/server/routes/linkTokens.js#L30-L35) and [LaunchLink.tsx](https://github.com/plaid/pattern/blob/master/client/src/components/LaunchLink.tsx#L42-L46) . These files contain the Link update mode code for the React-based [Plaid Pattern](https://github.com/plaid/pattern) sample app.

#### Account selection screens in update mode 

To demonstrate the user experience of various update mode flows, below are screenshots of update mode that correspond to different Account Select V2 settings.

(An image of "Account selection interface in Plaid Link showing options to connect accounts with WonderWallet, confirming account data sharing.")

Enabled for one account

(An image of "Plaid account selection screen showing multi-select feature; users choose accounts to share with WonderWallet, option to confirm changes.")

Enabled for multiple accounts

(An image of "Plaid Link UI showing account selection for Gingham Bank in update mode; includes accounts, balances, and 'Learn more' link.")

Enabled for all accounts

---


# Link - Web | Plaid Docs

Link Web SDK 
=============

#### Reference for integrating with the Link JavaScript SDK and React SDK 

Prefer to learn with code examples? Check out our [GitHub repo](https://github.com/plaid/tiny-quickstart) with working example Link implementations for both [JavaScript](https://github.com/plaid/tiny-quickstart/tree/main/vanilla_js) and [React](https://github.com/plaid/tiny-quickstart/tree/main/react) .

#### Installation 

Select group for content switcher

JavaScriptReact

Include the Plaid Link initialize script on each page of your site. It must always be loaded directly from `https://cdn.plaid.com`, rather than included in a bundle or hosted yourself. Unlike Plaid's other SDKs, the JavaScript web SDK is not versioned; `cdn.plaid.com` will automatically provide the latest available SDK.

```jsx

```

To get started with Plaid Link for React, clone the [GitHub repository](https://github.com/plaid/react-plaid-link) and review the example application and README, which provide reference implementations.

Next, you'll need to install the react-plaid-link package.

With npm:

```bash
npm install --save react-plaid-link
```

With yarn:

```bash
yarn add react-plaid-link
```

Then import the necessary components and types:

```tsx
import {
  usePlaidLink,
  PlaidLinkOptions,
  PlaidLinkOnSuccess,
} from 'react-plaid-link';
```

#### CSP directives 

If you are using a Content Security Policy (CSP), use the following directives to allow Link traffic:

```jsx
default-src https://cdn.plaid.com/;
script-src 'unsafe-inline' https://cdn.plaid.com/link/v2/stable/link-initialize.js;
frame-src https://cdn.plaid.com/;
connect-src https://production.plaid.com/;
```

If using Sandbox instead of Production, make sure to update the `connect-src` directive to point to the appropriate server (`https://sandbox.plaid.com`).

#### Creating a Link token 

Before you can create an instance of Link, you need to first create a `link_token`. A `link_token` can be configured for different Link flows and is used to control much of Link's behavior. To learn how to create a new `link_token`, see the API Reference entry for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

\=\*=\*=\*=

#### Create 

`Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com#open) , [exit](https://plaid.com#exit) , and [destroy](https://plaid.com#destroy) . Calling `open` will open Link and display the Consent Pane view, calling `exit` will close Link, and calling `destroy` will clean up the iframe.  
It is recommended to call `Plaid.create` when initializing the view that is responsible for loading Plaid, as this will allow Plaid to pre-initialize Link, resulting in lower UI latency upon calling `open`, which can increase Link conversion.  
When using the React SDK, this method is called `usePlaidLink` and returns an object with four values, [open](https://plaid.com#open) , [exit](https://plaid.com#exit) , `ready`, and `error`. The values `open` and `exit` behave as described above. `ready` is a passthrough for `onLoad` and will be `true` when Link is ready to be opened. `error` is populated only if Plaid fails to load the Link JavaScript. There is no separate method to destroy Link in the React SDK, as unmount will automatically destroy the Link instance.  
**Note:** Control whether or not your Link integration uses the Account Select view from the [Dashboard](https://dashboard.plaid.com/signin?redirect=%2Flink%2Faccount-select) .

**Properties**

[token](https://plaid.com/docs/link/web/index.html.md#link-web-create-token)

string

Specify a `link_token` to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for a full list of configurations.

[onSuccess](https://plaid.com/docs/link/web/index.html.md#link-web-create-onSuccess)

callback

A function that is called when a user successfully links an Item. The function should expect two arguments, the `public_token` and a `metadata` object. See [onSuccess](https://plaid.com#onsuccess) .

[onExit](https://plaid.com/docs/link/web/index.html.md#link-web-create-onExit)

callback

A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect two arguments, a nullable `error` object and a `metadata` object. See [onExit](https://plaid.com#onexit) .

[onEvent](https://plaid.com/docs/link/web/index.html.md#link-web-create-onEvent)

callback

A function that is called when a user reaches certain points in the Link flow. The function should expect two arguments, an `eventName` string and a `metadata` object. See [onEvent](https://plaid.com#onevent) .

[onLoad](https://plaid.com/docs/link/web/index.html.md#link-web-create-onLoad)

callback

A function that is called when the Link module has finished loading. Calls to `plaidLinkHandler.open()` prior to the `onLoad` callback will be delayed until the module is fully loaded.

[receivedRedirectUri](https://plaid.com/docs/link/web/index.html.md#link-web-create-receivedRedirectUri)

string

A `receivedRedirectUri` is required to support OAuth authentication flows when re-launching Link on a mobile device.

[key](https://plaid.com/docs/link/web/index.html.md#link-web-create-key)

deprecated, string

The `public_key` is no longer used for new implementations of Link. If your integration is still using a `public_key`, see the [migration guide](https://plaid.com/docs/link/link-token-migration-guide/index.html.md) to upgrade to using a `link_token`. See the [maintenance guide](https://plaid.com/docs/link/maintain-legacy-integration/index.html.md) to troubleshoot any `public_key` issues.

```tsx
// The usePlaidLink hook manages Plaid Link creation
// It does not return a destroy function;
// instead, on unmount it automatically destroys the Link instance
const config: PlaidLinkOptions = {
  onSuccess: (public_token, metadata) => {}
  onExit: (err, metadata) => {}
  onEvent: (eventName, metadata) => {}
  token: 'GENERATED_LINK_TOKEN',
};


const { open, exit, ready } = usePlaidLink(config);
```

\=\*=\*=\*=

#### onSuccess 

The `onSuccess` callback is called when a user successfully links an Item. It takes two arguments: the `public_token` and a `metadata` object.

**Properties**

[public\_token](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-public-token)

string

Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used.

[metadata](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata)

object

Displayed once a user has successfully completed Link.

[institution](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-institution)

nullable, object

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-institution-name)

string

The full institution name, such as `'Wells Fargo'`

[institution\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-institution-institution-id)

string

The Plaid institution identifier

[accounts](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts)

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](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-id)

string

The Plaid `account_id`

[name](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-name)

string

The official account name

[mask](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-mask)

nullable, 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](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-type)

string

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[subtype](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-subtype)

string

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[verification\_status](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-verification-status)

nullable, string

Indicates an Item's micro-deposit-based verification or database verification status. 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 deposit.  
`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.  
`database_matched`: The Item has successfully been verified using Plaid's data sources.  
`database_insights_pending`: The Database Insights result is pending and will be available upon Auth request.  
`null`: Neither micro-deposit-based verification nor database verification are being used for the Item.

[class\_type](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts-class-type)

nullable, string

If micro-deposit verification is being used, indicates whether the account being verified is a `business` or `personal` account.

[account](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-account)

deprecated, nullable, object

Deprecated. Use `accounts` instead.

[link\_session\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-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](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-transfer-status)

nullable, string

The status of a transfer. Returned only when [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) is implemented.  

*   `COMPLETE` – The transfer was completed.
*   `INCOMPLETE` – The transfer could not be completed. For help, see [Troubleshooting transfers](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#troubleshooting-transfers) .

  
  

Possible values: `COMPLETE`, `INCOMPLETE`

```tsx
import {
  PlaidLinkOnSuccess,
  PlaidLinkOnSuccessMetadata,
} from 'react-plaid-link';


const onSuccess = useCallback(
  (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
    // log and save metadata
    // exchange public token (if using Item-based products)
    fetch('//yourserver.com/exchange-public-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: {
        public_token,
      },
    });
  },
  [],
);
```

```javascript
{
  institution: {
    name: 'Wells Fargo',
    institution_id: 'ins_4'
  },
  accounts: [
    {
      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
      name: 'Plaid Checking',
      mask: '0000',
      type: 'depository',
      subtype: 'checking',
      verification_status: null
    },
    {
      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
      name: 'Plaid Saving',
      mask: '1111',
      type: 'depository',
      subtype: 'savings'
    }
    ...
  ],
  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
}
```

\=\*=\*=\*=

#### onExit 

The `onExit` callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. `onExit` takes two arguments, a nullable `error` object and a `metadata` object. The `metadata` parameter is always present, though some values may be `null`. Note that `onExit` will not be called when Link is destroyed in some other way than closing Link, such as the user hitting the browser back button or closing the browser tab on which the Link session is present.

**Properties**

[error](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-error)

nullable, object

A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.

[error\_type](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-error-error-type)

String

A broad categorization of the error.

[error\_code](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-error-error-code)

String

The particular error code. Each `error_type` has a specific set of `error_codes`.

[error\_message](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-error-error-message)

String

A developer-friendly representation of the error code.

[display\_message](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-error-display-message)

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

[metadata](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata)

object

Displayed if a user exits Link without successfully linking an Item.

[institution](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-institution)

nullable, object

An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`.

[name](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-institution-name)

string

The full institution name, such as `Wells Fargo`

[institution\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-institution-institution-id)

string

The Plaid institution identifier

[status](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status)

string

The point at which the user exited the Link flow. One of the following values.

[requires\_questions](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-requires-questions)

User prompted to answer security questions

[requires\_selections](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-requires-selections)

User prompted to answer multiple choice question(s)

[requires\_code](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-requires-code)

User prompted to provide a one-time passcode

[choose\_device](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-choose-device)

User prompted to select a device on which to receive a one-time passcode

[requires\_credentials](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-requires-credentials)

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

[requires\_account\_selection](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-requires-account-selection)

User prompted to select one or more financial accounts to share

[requires\_oauth](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-requires-oauth)

User prompted to enter an OAuth flow

[institution\_not\_found](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-institution-not-found)

User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.

[institution\_not\_supported](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-status-institution-not-supported)

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

[link\_session\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-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](https://plaid.com/docs/link/web/index.html.md#link-web-onexit-metadata-request-id)

string

The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.

```tsx
import {
  PlaidLinkOnExit,
  PlaidLinkOnExitMetadata,
  PlaidLinkError,
} from 'react-plaid-link';


const onExit = useCallback(
  (error: PlaidLinkError, metadata: PlaidLinkOnExitMetadata) => {
    // log and save error and metadata
    // handle invalid link token
    if (error != null && error.error_code === 'INVALID_LINK_TOKEN') {
      // generate new link token
    }
    // to handle other error codes, see https://plaid.com/docs/errors/
  },
  [],
);
```

```javascript
{
  error_type: 'ITEM_ERROR',
  error_code: 'INVALID_CREDENTIALS',
  error_message: 'the credentials were not correct',
  display_message: 'The credentials were not correct.',
}
```

```javascript
{
  institution: {
    name: 'Wells Fargo',
    institution_id: 'ins_4'
  },
  status: 'requires_credentials',
  link_session_id: '36e201e0-2280-46f0-a6ee-6d417b450438',
  request_id: '8C7jNbDScC24THu'
}
```

\=\*=\*=\*=

#### onEvent 

The `onEvent` callback is called at certain points in the Link flow. It takes two arguments, an `eventName` string and a `metadata` object.  
The `metadata` parameter is always present, though some values may be `null`. Note that new `eventNames`, `metadata` keys, or view names may be added without notice.  
The `OPEN`, `LAYER_READY`, and `LAYER_NOT_AVAILABLE` events will fire in real time; subsequent events will fire at the end of the Link flow, along with the `onSuccess` or `onExit` callback. Callback ordering is not guaranteed; `onEvent` callbacks may fire before, after, or surrounding the `onSuccess` or `onExit` callback, and event callbacks are not guaranteed to fire in the order in which they occurred. If you need to determine the exact time when an event happened, use the `timestamp` in the metadata.  
The following callback events are stable, which means that they are suitable for programmatic use in your application's logic: `OPEN`, `EXIT`, `HANDOFF`, `SELECT_INSTITUTION`, `ERROR`, `BANK_INCOME_INSIGHTS_COMPLETED`, `IDENTITY_VERIFICATION_PASS_SESSION`, `IDENTITY_VERIFICATION_FAIL_SESSION`, `IDENTITY_MATCH_FAILED`, `IDENTITY_MATCH_PASSED`, `LAYER_READY`, `LAYER_NOT_AVAILABLE`. The remaining callback events are informational and subject to change and should be used for analytics and troubleshooting purposes only.

**Properties**

[eventName](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName)

string

A string representing the event that has just occurred in the Link flow.

[AUTO\_SUBMIT\_PHONE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-AUTO-SUBMIT-PHONE)

The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid.

[BANK\_INCOME\_INSIGHTS\_COMPLETED](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-BANK-INCOME-INSIGHTS-COMPLETED)

The user has completed the Assets and Bank Income Insights flow.

[CLOSE\_OAUTH](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-CLOSE-OAUTH)

The user closed the third-party website or mobile app without completing the OAuth flow.

[CONNECT\_NEW\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-CONNECT-NEW-INSTITUTION)

The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Returning User Experience flow.

[ERROR](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-ERROR)

A recoverable error occurred in the Link flow, see the `error_code` metadata.

[EXIT](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-EXIT)

The user has exited without completing the Link flow and the [onExit](https://plaid.com#onexit) callback is fired.

[FAIL\_OAUTH](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-FAIL-OAUTH)

The user encountered an error while completing the third-party's OAuth login flow.

[HANDOFF](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-HANDOFF)

The user has exited Link after successfully linking an Item.

[IDENTITY\_MATCH\_FAILED](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-MATCH-FAILED)

An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match.

[IDENTITY\_MATCH\_PASSED](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-MATCH-PASSED)

An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match.

[IDENTITY\_VERIFICATION\_START\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-START-STEP)

The user has started a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_PASS\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PASS-STEP)

The user has passed a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_FAIL\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-FAIL-STEP)

The user has failed a step of the Identity Verification flow. The step is indicated by `view_name`.

[IDENTITY\_VERIFICATION\_PENDING\_REVIEW\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PENDING-REVIEW-STEP)

The user has reached the pending review state.

[IDENTITY\_VERIFICATION\_CREATE\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-CREATE-SESSION)

The user has started a new Identity Verification session.

[IDENTITY\_VERIFICATION\_RESUME\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-RESUME-SESSION)

The user has resumed an existing Identity Verification session.

[IDENTITY\_VERIFICATION\_PASS\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PASS-SESSION)

The user has passed their Identity Verification session.

[IDENTITY\_VERIFICATION\_FAIL\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-FAIL-SESSION)

The user has failed their Identity Verification session.

[IDENTITY\_VERIFICATION\_PENDING\_REVIEW\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PENDING-REVIEW-SESSION)

The user has completed their Identity Verification session, which is now in a pending review state.

[IDENTITY\_VERIFICATION\_OPEN\_UI](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-OPEN-UI)

The user has opened the UI of their Identity Verification session.

[IDENTITY\_VERIFICATION\_RESUME\_UI](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-RESUME-UI)

The user has resumed the UI of their Identity Verification session.

[IDENTITY\_VERIFICATION\_CLOSE\_UI](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-CLOSE-UI)

The user has closed the UI of their Identity Verification session.

[LAYER\_AUTOFILL\_NOT\_AVAILABLE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-LAYER-AUTOFILL-NOT-AVAILABLE)

The user's date of birth passed to Link is not eligible for Layer autofill.

[LAYER\_NOT\_AVAILABLE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-LAYER-NOT-AVAILABLE)

The user phone number passed to Link is not eligible for Layer.

[LAYER\_READY](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-LAYER-READY)

The user phone number passed to Link is eligible for Layer and `open()` may now be called.

[MATCHED\_SELECT\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-MATCHED-SELECT-INSTITUTION)

The user selected an institution that was presented as a matched institution. This event can be emitted if [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) is being used, if the institution was surfaced as a matched institution likely to have been linked to Plaid by a returning user, or if the institution's `routing_number` was provided when calling `/link/token/create`. For details on which scenario is triggering the event, see `metadata.matchReason`.

[OPEN](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-OPEN)

The user has opened Link.

[OPEN\_MY\_PLAID](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-OPEN-MY-PLAID)

The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product

[OPEN\_OAUTH](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-OPEN-OAUTH)

The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.

[SEARCH\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SEARCH-INSTITUTION)

The user has searched for an institution.

[SELECT\_AUTH\_TYPE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-AUTH-TYPE)

The user has chosen whether to Link instantly or manually (i.e., with micro-deposits). This event emits the `selection` metadata to indicate the user's selection.

[SELECT\_BRAND](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-BRAND)

The user selected a brand, e.g. Bank of America. The `SELECT_BRAND` event is only emitted for large financial institutions with multiple online banking portals.

[SELECT\_DEGRADED\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-DEGRADED-INSTITUTION)

The user selected an institution with a `DEGRADED` health status and was shown a corresponding message.

[SELECT\_DOWN\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-DOWN-INSTITUTION)

The user selected an institution with a `DOWN` health status and was shown a corresponding message.

[SELECT\_FILTERED\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-FILTERED-INSTITUTION)

The user selected an institution Plaid does not support all requested products for and was shown a corresponding message.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-INSTITUTION)

The user selected an institution.

[SKIP\_SUBMIT\_PHONE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SKIP-SUBMIT-PHONE)

The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_ACCOUNT\_NUMBER](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-ACCOUNT-NUMBER)

The user has submitted an account number. This event emits the `account_number_mask` metadata to indicate the mask of the account number the user provided.

[SUBMIT\_CREDENTIALS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-CREDENTIALS)

The user has submitted credentials.

[SUBMIT\_DOCUMENTS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-DOCUMENTS)

The user is being prompted to submit documents for an Income verification flow.

[SUBMIT\_DOCUMENTS\_ERROR](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-DOCUMENTS-ERROR)

The user encountered an error when submitting documents for an Income verification flow.

[SUBMIT\_DOCUMENTS\_SUCCESS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-DOCUMENTS-SUCCESS)

The user has successfully submitted documents for an Income verification flow.

[SUBMIT\_MFA](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-MFA)

The user has submitted MFA.

[SUBMIT\_OTP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-OTP)

The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_PHONE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-PHONE)

The user has submitted their phone number. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_ROUTING\_NUMBER](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SUBMIT-ROUTING-NUMBER)

The user has submitted a routing number. This event emits the `routing_number` metadata to indicate user's routing number.

[TRANSITION\_VIEW](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-TRANSITION-VIEW)

The `TRANSITION_VIEW` event indicates that the user has moved from one view to the next.

[VERIFY\_PHONE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-VERIFY-PHONE)

The user has successfully verified their phone number. This event is only emitted in the Link Returning User Experience flow.

[VIEW\_DATA\_TYPES](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-VIEW-DATA-TYPES)

The user has viewed data types on the data transparency consent pane.

[metadata](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata)

object

An object containing information about the event.

[account\_number\_mask](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-account-number-mask)

nullable, 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`.

[error\_type](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-error-type)

nullable, string

The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.

[error\_code](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-error-code)

nullable, string

The error code that the user encountered. Emitted by `ERROR`, `EXIT`.

[error\_message](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-error-message)

nullable, string

The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.

[exit\_status](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-exit-status)

nullable, string

The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`

[institution\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-institution-id)

nullable, string

The ID of the selected institution. Emitted by: _all events_.

[institution\_name](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-institution-name)

nullable, string

The name of the selected institution. Emitted by: _all events_.

[institution\_search\_query](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-institution-search-query)

nullable, string

The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.

[is\_update\_mode](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-is-update-mode)

nullable, string

Indicates if the current Link session is an update mode session. Emitted by: `OPEN`.

[match\_reason](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-match-reason)

nullable, 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](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-routing-number)

nullable, string

The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`.

[mfa\_type](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-mfa-type)

nullable, 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](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name)

nullable, string

The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`.

[ACCEPT\_TOS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-ACCEPT-TOS)

The view showing Terms of Service in the identity verification flow.

[CONNECTED](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-CONNECTED)

The user has connected their account.

[CONSENT](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-CONSENT)

We ask the user to consent to the privacy policy.

[CREDENTIAL](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-CREDENTIAL)

Asking the user for their account credentials.

[DOCUMENTARY\_VERIFICATION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-DOCUMENTARY-VERIFICATION)

The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).

[ERROR](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-ERROR)

An error has occurred.

[EXIT](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-EXIT)

Confirming if the user wishes to close Link.

[INSTANT\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-INSTANT-MICRODEPOSIT-AUTHORIZED)

The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.

[KYC\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-KYC-CHECK)

The view representing the "know your customer" step in the identity verification flow.

[LOADING](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-LOADING)

Link is making a request to our servers.

[MFA](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-MFA)

The user is asked by the institution for additional MFA authentication.

[NUMBERS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-NUMBERS)

The user is asked to insert their account and routing numbers.

[NUMBERS\_SELECT\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-NUMBERS-SELECT-INSTITUTION)

The user goes through the Same Day micro-deposits flow with Reroute to Credentials.

[OAUTH](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-OAUTH)

The user is informed they will authenticate with the financial institution via OAuth.

[PROFILE\_DATA\_REVIEW](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-PROFILE-DATA-REVIEW)

The user is asked to review their profile data in the Layer flow.

[RECAPTCHA](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-RECAPTCHA)

The user was presented with a Google reCAPTCHA to verify they are human.

[RISK\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-RISK-CHECK)

The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).

[SAME\_DAY\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SAME-DAY-MICRODEPOSIT-AUTHORIZED)

The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.

[SCREENING](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SCREENING)

The watchlist screening step in the identity verification flow.

[SELECT\_ACCOUNT](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELECT-ACCOUNT)

We ask the user to choose an account.

[SELECT\_AUTH\_TYPE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELECT-AUTH-TYPE)

The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).

[SELECT\_BRAND](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELECT-BRAND)

The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELECT-INSTITUTION)

We ask the user to choose their institution.

[SELECT\_SAVED\_ACCOUNT](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELECT-SAVED-ACCOUNT)

The user is asked to select their saved accounts and/or new accounts for linking in the Link Returning User Experience flow.

[SELECT\_SAVED\_INSTITUTION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELECT-SAVED-INSTITUTION)

The user is asked to pick a saved institution or link a new one in the Link Returning User Experience flow.

[SELFIE\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELFIE-CHECK)

The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.

[SUBMIT\_PHONE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SUBMIT-PHONE)

The user is asked for their phone number in the Link Returning User Experience flow.

[UPLOAD\_DOCUMENTS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-UPLOAD-DOCUMENTS)

The user is asked to upload documents (for Income verification).

[VERIFY\_PHONE](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-VERIFY-PHONE)

The user is asked to verify their phone in the Link Returning User Experience flow.

[VERIFY\_SMS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-VERIFY-SMS)

The SMS verification step in the identity verification flow.

[request\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-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_.

[link\_session\_id](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-link-session-id)

string

The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_.

[timestamp](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-timestamp)

string

An ISO 8601 representation of when the event occurred. For example `2017-09-14T14:42:19.350Z`. Emitted by: _all events_.

[selection](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-selection)

nullable, string

The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`.

```tsx
import {
  PlaidLinkOnEvent,
  PlaidLinkOnEventMetadata,
  PlaidLinkStableEvent,
} from 'react-plaid-link';


const onEvent = useCallback(
  (
    eventName: PlaidLinkStableEvent | string,
    metadata: PlaidLinkOnEventMetadata,
  ) => {
    // log eventName and metadata
  },
  [],
);
```

```javascript
{
  error_type: 'ITEM_ERROR',
  error_code: 'INVALID_CREDENTIALS',
  error_message: 'the credentials were not correct',
  exit_status: null,
  institution_id: 'ins_4',
  institution_name: 'Wells Fargo',
  institution_search_query: 'wellsf',
  mfa_type: null,
  view_name: 'ERROR'
  request_id: 'm8MDnv9okwxFNBV',
  link_session_id: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
  timestamp: '2017-09-14T14:42:19.350Z',
  selection: null,
}
```

\=\*=\*=\*=

#### open() 

Calling `open` will display the Consent Pane view to your user, starting the Link flow. Once `open` is called, you will begin receiving events via the [onEvent callback](https://plaid.com#onevent) .

```tsx
const { open, exit, ready } = usePlaidLink(config);


// Open Link
if (ready) {
  open();
}
```

\=\*=\*=\*=

#### exit() 

The `exit` function allows you to programmatically close Link. Calling `exit` will trigger either the [onExit](https://plaid.com#onexit) or [onSuccess](https://plaid.com#onsuccess) callbacks.  
The `exit` function takes a single, optional argument, a configuration `Object`.

**Properties**

[force](https://plaid.com/docs/link/web/index.html.md#link-web-exit-force)

boolean

If `true`, Link will exit immediately. If `false`, or the option is not provided, an exit confirmation screen may be presented to the user.

```tsx
const { open, exit, ready } = usePlaidLink(config);


// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
exit();
```

```tsx
const { open, exit, ready } = usePlaidLink(config);


// Force exit - Link exits immediately
exit({ force: true });
```

#### destroy() 

The `destroy` function allows you to destroy the Link handler instance, properly removing any DOM artifacts that were created by it. Use `destroy()` when creating new replacement Link handler instances in the `onExit` callback.

```tsx
// On unmount usePlaidLink hook automatically destroys any
// existing link instance
```

\=\*=\*=\*=

#### submit 

The `submit` function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number).

**Properties**

[phone\_number](https://plaid.com/docs/link/web/index.html.md#link-web-submit-phone-number)

string

The user's phone number.

[date\_of\_birth](https://plaid.com/docs/link/web/index.html.md#link-web-submit-date-of-birth)

string

The user's date of birth. To be provided in the format "yyyy-mm-dd".

```tsx
const { open, exit, submit } = usePlaidLink(config);


// After collecting a user phone number...
submit({
    "phone_number": "+14155550123"
});
```

\=\*=\*=\*=

#### OAuth 

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) .

\=\*=\*=\*=

#### Supported browsers 

Plaid officially supports Link on the latest versions of Chrome, Firefox, Safari, and Edge. Browsers are supported on Windows, Mac, Linux, iOS, and Android. Previous browser versions are also supported, as long as they are actively maintained; Plaid does not support browser versions that are no longer receiving patch updates, or that have been assigned official end of life (EOL) or end of support (EOS) status.

Ad-blocking software is not officially supported with Link web, and some ad-blockers have known to cause conflicts with Link.

\=\*=\*=\*=

#### Example code in Plaid Pattern 

For a real-life example of using Plaid Link for React, see [LaunchLink.tsx](https://github.com/plaid/pattern/blob/master/client/src/components/LaunchLink.tsx) . This file illustrates the code for implementation of Plaid Link for React for the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app.

---


# Link - Webview integrations | Plaid Docs

Link Webview SDK 
=================

#### Reference for integrating with the Link Webview JavaScript SDK 

Using webviews to present Link is deprecated. If you're currently integrating this way, we recommend migrating to [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) or one Plaid's official SDKs for [Android](https://plaid.com/docs/link/android/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , and [React Native](https://plaid.com/docs/link/react-native/index.html.md) .

All Webview-based integrations need to extend the Webview handler for redirects in order to support connections to Chase. This can be accomplished with code samples for [iOS](https://github.com/plaid/plaid-link-examples/blob/master/webviews/wkwebview/wkwebview/LinkViewController.swift#L56-L72) and [Android](https://github.com/plaid/plaid-link-examples/blob/master/webviews/android/LinkWebview/app/src/main/java/com/example/linkwebview/MainActivity.kt#L89-L156) . For more details, see [Extending webview instances to support certain institutions](https://plaid.com/docs/link/oauth/index.html.md#extending-webview-instances-to-support-certain-institutions) in the OAuth Guide and the [in-process Webview deprecation notice](https://plaid.docsend.com/view/h3qdupjusiwyjvv5) . Webview-based integrations that do not extend the Webview handler are not supported by Chase and may be blocked by Chase in the future.

If your integration does not connect to Chase (for example, because you use only Identity Verification, Document Income, or Payroll Income, or you do not support end users in the US) you may ignore this warning.

\=\*=\*=\*=

#### Overview 

To integrate and use Plaid Link inside a Webview, we recommend starting with one of our sample Webview apps:

*   [iOS WKWebView](https://github.com/plaid/plaid-link-examples/tree/master/webviews/wkwebview)
*   [Android Webview](https://github.com/plaid/plaid-link-examples/tree/master/webviews/android)

Each example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects.

(An image of "Link webview")

\=\*=\*=\*=

#### Installation 

Link is optimized to work within Webviews, including on iOS and Android. The Link initialization URL to use for Webviews is:

```jsx
https://cdn.plaid.com/link/v2/stable/link.html
```

The Link configuration options for a Webview integration are passed via querystring rather than via a client-side JavaScript call. See the [create](https://plaid.com/docs/link/webview/index.html.md#create) section below for details on the available initialization parameters.

##### Communication between Link and your app 

Communication between the Webview and your app is handled by HTTP redirects rather than client-side JavaScript callbacks. These redirects should be intercepted by your app. The [example apps](https://github.com/plaid/plaid-link-examples) include sample code to do this.

All redirect URLs have the scheme `plaidlink`. The event type is communicated via the URL host and data is passed via the querystring.

```jsx
plaidlink://
```

There are three supported events, [connected](https://plaid.com/docs/link/webview/index.html.md#connected) , [exit](https://plaid.com/docs/link/webview/index.html.md#exit) , and [event](https://plaid.com/docs/link/webview/index.html.md#event) , which are documented below.

\=\*=\*=\*=

#### Create 

**Properties**

[isWebview](https://plaid.com/docs/link/webview/index.html.md#link-webview-create-isWebview)

boolean

Set to `true`, to trigger the Webview integration.

[token](https://plaid.com/docs/link/webview/index.html.md#link-webview-create-token)

string

Specify a `link_token` to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for a full list of configurations.

[receivedRedirectUri](https://plaid.com/docs/link/webview/index.html.md#link-webview-create-receivedRedirectUri)

string

A `receivedRedirectUri` is required to support OAuth authentication flows when re-launching Link on a mobile device. Note that any unsafe ASCII characters in the `receivedRedirectUri` in the webview query string must be URL-encoded.

[key](https://plaid.com/docs/link/webview/index.html.md#link-webview-create-key)

deprecated, string

The `public_key` is no longer used for new implementations of Link. If your integration is still using a `public_key`, see the [migration guide](https://plaid.com/docs/link/link-token-migration-guide/index.html.md) to upgrade to using a `link_token`. See the [maintenance guide](https://plaid.com/docs/link/maintain-legacy-integration/index.html.md) to troubleshoot any `public_key` issues.

```undefined
https://cdn.plaid.com/link/v2/stable/link.html
  ?isWebview=true
  &token="GENERATED_LINK_TOKEN"
  &receivedRedirectUri=
```

\=\*=\*=\*=

#### connected 

The `connected` event is analogous to the `onSuccess` callback in [Link Web](https://plaid.com/docs/link/web/index.html.md) and is sent when a user successfully completes Link. The following information is available from the querystring event:

**Properties**

[public\_token](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-public-token)

string

Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used.

[institution\_name](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-institution-name)

string

The full institution name, such as `'Wells Fargo'`

[institution\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-institution-id)

string

The Plaid institution identifier

[accounts](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts)

object

A JSON-stringified representation of the account(s) attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts.

[\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts--id)

string

The Plaid `account_id`

[meta](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-meta)

object

The account metadata

[name](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-meta-name)

string

The official account name

[number](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-meta-number)

nullable, 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](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-type)

string

The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[subtype](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-subtype)

string

The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values

[verification\_status](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-verification-status)

string

When all Auth features are enabled by initializing Link with the user object, the accounts object includes an Item's `verification_status`. See Auth accounts for a full list of possible values.

[class\_type](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-accounts-class-type)

nullable, string

If micro-deposit verification is being used, indicates whether the account being verified is a `business` or `personal` account.

[transfer\_status](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-transfer-status)

nullable, string

The status of a transfer. Returned only when [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) is implemented.  

*   `COMPLETE` – The transfer was completed.
*   `INCOMPLETE` – The transfer could not be completed. For help, see [Troubleshooting transfers](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#troubleshooting-transfers) .

  
  

Possible values: `COMPLETE`, `INCOMPLETE`

[link\_session\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-connected-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.

```undefined
plaidlink://connected
  ?public_token=public-sandbox-fb7cca4a-82e6-4707
  &institution_id=ins_3
  &institution_name=Chase
  &accounts='[{"_id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "meta": {"name":"Plaid Savings", "number": "0000"}, "subtype": "checking", "type": "depository" }]'
  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
```

```json
"accounts": [
  {
    "_id": "ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy",
    "meta": {
      "name": "Plaid Checking",
      "number": "0000",
    },
    "type": "depository",
    "subtype": "checking",
    "verification_status": null
  },
  {
    "_id": "9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4",
    "meta": {
      "name": "Plaid Saving",
      "number": "1111"
    },
    "type": "depository",
    "subtype": "savings"
  }
  ...
]
```

\=\*=\*=\*=

#### exit 

The `exit` event is analogous to the `onExit` callback and is sent when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. Note that on Android devices, an `exit` event will not be sent if the user exits Link through a system action, such as hitting the browser back button. The following information is available from the querystring:

**Properties**

[status](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status)

string

The point at which the user exited the Link flow. One of the following values.

[requires\_questions](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-requires-questions)

User prompted to answer security questions

[requires\_selections](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-requires-selections)

User prompted to answer multiple choice question(s)

[requires\_code](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-requires-code)

User prompted to provide a one-time passcode

[choose\_device](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-choose-device)

User prompted to select a device on which to receive a one-time passcode

[requires\_credentials](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-requires-credentials)

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

[requires\_account\_selection](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-requires-account-selection)

User prompted to select one or more financial accounts to share

[requires\_oauth](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-requires-oauth)

User prompted to enter an OAuth flow

[institution\_not\_found](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-institution-not-found)

User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.

[institution\_not\_supported](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-status-institution-not-supported)

User exited the Link flow after discovering their selected institution is no longer supported by Plaid

[error\_type](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-error-type)

String

A broad categorization of the error.

[error\_code](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-error-code)

String

The particular error code. Each `error_type` has a specific set of `error_codes`.

[error\_message](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-error-message)

String

A developer-friendly representation of the error code.

[display\_message](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-display-message)

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

[institution\_name](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-institution-name)

string

The full institution name, such as `Wells Fargo`

[institution\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-institution-id)

string

The Plaid institution identifier

[link\_session\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-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](https://plaid.com/docs/link/webview/index.html.md#link-webview-exit-request-id)

string

The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.

```undefined
plaidlink://exit
  ?status=requires_credentials
  &error_type=ITEM_ERROR
  &error_code=ITEM_LOGIN_REQUIRED
  &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again.
  &error_message=the%20credentials%20were%20not%20correct
  &institution_id=ins_3
  &institution_name=Chase
  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
  &request_id=m8MDnv9okwxFNBV
```

\=\*=\*=\*=

#### event 

The `event` message is analogous to the Link Web [onEvent callback](https://plaid.com/docs/link/web/index.html.md#onevent) and is called as the user moves through the Link flow. The querystring will always contain all possible keys, though not all keys will have values. The `event_name` will dictate which keys are populated.

**Properties**

[event\_name](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name)

string

A string representing the event that has just occurred in the Link flow.

[AUTO\_SUBMIT\_PHONE](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-AUTO-SUBMIT-PHONE)

The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid.

[BANK\_INCOME\_INSIGHTS\_COMPLETED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-BANK-INCOME-INSIGHTS-COMPLETED)

The user has completed the Assets and Bank Income Insights flow.

[CLOSE\_OAUTH](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-CLOSE-OAUTH)

The user closed the third-party website or mobile app without completing the OAuth flow.

[CONNECT\_NEW\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-CONNECT-NEW-INSTITUTION)

The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Returning User Experience flow.

[ERROR](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-ERROR)

A recoverable error occurred in the Link flow, see the `error_code` metadata.

[EXIT](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-EXIT)

The user has exited without completing the Link flow and the [exit](https://plaid.com#exit) callback is fired.

[FAIL\_OAUTH](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-FAIL-OAUTH)

The user encountered an error while completing the third-party's OAuth login flow.

[HANDOFF](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-HANDOFF)

The user has exited Link after successfully linking an Item.

[IDENTITY\_MATCH\_FAILED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-IDENTITY-MATCH-FAILED)

An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match.

[IDENTITY\_MATCH\_PASSED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-IDENTITY-MATCH-PASSED)

An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match.

[INSTANT\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-INSTANT-MICRODEPOSIT-AUTHORIZED)

The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.

[MATCHED\_SELECT\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-MATCHED-SELECT-INSTITUTION)

The user selected an institution that was presented as a matched institution. This event can be emitted if [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) is being used, if the institution was surfaced as a matched institution likely to have been linked to Plaid by a returning user, or if the institution's `routing_number` was provided when calling `/link/token/create`. For details on which scenario is triggering the event, see `metadata.matchReason`.

[OPEN](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-OPEN)

The user has opened Link.

[OPEN\_MY\_PLAID](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-OPEN-MY-PLAID)

The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product

[OPEN\_OAUTH](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-OPEN-OAUTH)

The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.

[SAME\_DAY\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SAME-DAY-MICRODEPOSIT-AUTHORIZED)

The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.

[SEARCH\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SEARCH-INSTITUTION)

The user has searched for an institution.

[SELECT\_BRAND](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SELECT-BRAND)

The user selected a brand, e.g. Bank of America. The `SELECT_BRAND` event is only emitted for large financial institutions with multiple online banking portals.

[SELECT\_DEGRADED\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SELECT-DEGRADED-INSTITUTION)

The user selected an institution with a `DEGRADED` health status and was shown a corresponding message.

[SELECT\_DOWN\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SELECT-DOWN-INSTITUTION)

The user selected an institution with a `DOWN` health status and was shown a corresponding message.

[SELECT\_FILTERED\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SELECT-FILTERED-INSTITUTION)

The user selected an institution Plaid does not support all requested products for and was shown a corresponding message.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SELECT-INSTITUTION)

The user selected an institution.

[SKIP\_SUBMIT\_PHONE](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SKIP-SUBMIT-PHONE)

The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_ACCOUNT\_NUMBER](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-ACCOUNT-NUMBER)

The user has submitted an account number. This event emits the `account_number_mask` metadata to indicate the mask of the account number the user provided.

[SUBMIT\_CREDENTIALS](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-CREDENTIALS)

The user has submitted credentials.

[SUBMIT\_DOCUMENTS](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-DOCUMENTS)

The user is being prompted to submit documents for an Income verification flow.

[SUBMIT\_DOCUMENTS\_ERROR](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-DOCUMENTS-ERROR)

The user encountered an error when submitting documents for an Income verification flow.

[SUBMIT\_DOCUMENTS\_SUCCESS](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-DOCUMENTS-SUCCESS)

The user has successfully submitted documents for an Income verification flow.

[SUBMIT\_MFA](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-MFA)

The user has submitted MFA.

[SUBMIT\_OTP](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-OTP)

The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_PHONE](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-PHONE)

The user has submitted their phone number. This event is only emitted in the Link Returning User Experience flow.

[SUBMIT\_ROUTING\_NUMBER](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-SUBMIT-ROUTING-NUMBER)

The user has submitted a routing number. This event emits the `routing_number` metadata to indicate user's routing number.

[TRANSITION\_VIEW](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-TRANSITION-VIEW)

The `TRANSITION_VIEW` event indicates that the user has moved from one view to the next.

[VERIFY\_PHONE](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-VERIFY-PHONE)

The user has successfully verified their phone number. This event is only emitted in the Link Returning User Experience flow.

[VIEW\_DATA\_TYPES](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-event-name-VIEW-DATA-TYPES)

The user has viewed data types on the data transparency consent pane.

[error\_type](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-error-type)

nullable, string

The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.

[error\_code](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-error-code)

nullable, string

The error code that the user encountered. Emitted by `ERROR`, `EXIT`.

[error\_message](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-error-message)

nullable, string

The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.

[exit\_status](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-exit-status)

nullable, string

The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`

[institution\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-institution-id)

nullable, string

The ID of the selected institution. Emitted by: _all events_.

[institution\_name](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-institution-name)

nullable, string

The name of the selected institution. Emitted by: _all events_.

[institution\_search\_query](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-institution-search-query)

nullable, string

The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.

[is\_update\_mode](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-is-update-mode)

nullable, string

Indicates if the current Link session is an update mode session. Emitted by: `OPEN`.

[match\_reason](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-match-reason)

nullable, 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`.

[mfa\_type](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-mfa-type)

nullable, 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](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name)

nullable, string

The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`.

[ACCEPT\_TOS](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-ACCEPT-TOS)

The view showing Terms of Service in the identity verification flow.

[CONNECTED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-CONNECTED)

The user has connected their account.

[CONSENT](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-CONSENT)

We ask the user to consent to the privacy policy.

[CREDENTIAL](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-CREDENTIAL)

Asking the user for their account credentials.

[DOCUMENTARY\_VERIFICATION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-DOCUMENTARY-VERIFICATION)

The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).

[ERROR](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-ERROR)

An error has occurred.

[EXIT](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-EXIT)

Confirming if the user wishes to close Link.

[INSTANT\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-INSTANT-MICRODEPOSIT-AUTHORIZED)

The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.

[KYC\_CHECK](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-KYC-CHECK)

The view representing the "know your customer" step in the identity verification flow.

[LOADING](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-LOADING)

Link is making a request to our servers.

[MFA](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-MFA)

The user is asked by the institution for additional MFA authentication.

[NUMBERS](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-NUMBERS)

The user is asked to insert their account and routing numbers.

[OAUTH](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-OAUTH)

The user is informed they will authenticate with the financial institution via OAuth.

[RECAPTCHA](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-RECAPTCHA)

The user was presented with a Google reCAPTCHA to verify they are human.

[RISK\_CHECK](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-RISK-CHECK)

The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).

[SAME\_DAY\_MICRODEPOSIT\_AUTHORIZED](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SAME-DAY-MICRODEPOSIT-AUTHORIZED)

The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.

[SCREENING](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SCREENING)

The watchlist screening step in the identity verification flow.

[SELECT\_ACCOUNT](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SELECT-ACCOUNT)

We ask the user to choose an account.

[SELECT\_BRAND](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SELECT-BRAND)

The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

[SELECT\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SELECT-INSTITUTION)

We ask the user to choose their institution.

[SELECT\_SAVED\_ACCOUNT](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SELECT-SAVED-ACCOUNT)

The user is asked to select their saved accounts and/or new accounts for linking in the Link Returning User Experience flow.

[SELECT\_SAVED\_INSTITUTION](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SELECT-SAVED-INSTITUTION)

The user is asked to pick a saved institution or link a new one in the Link Returning User Experience flow.

[SELFIE\_CHECK](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SELFIE-CHECK)

The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.

[SUBMIT\_PHONE](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-SUBMIT-PHONE)

The user is asked for their phone number in the Link Returning User Experience flow.

[VERIFY\_PHONE](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-VERIFY-PHONE)

The user is asked to verify their phone in the Link Returning User Experience flow.

[VERIFY\_SMS](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-view-name-VERIFY-SMS)

The SMS verification step in the identity verification flow.

[request\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-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_.

[link\_session\_id](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-link-session-id)

string

The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_.

[timestamp](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-timestamp)

string

An ISO 8601 representation of when the event occurred. For example `2017-09-14T14:42:19.350Z`. Emitted by: _all events_.

[selection](https://plaid.com/docs/link/webview/index.html.md#link-webview-event-selection)

nullable, string

The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`.

```undefined
plaidlink://event
  &event_name=SELECT_INSTITUTION
  ?error_type=ITEM_ERROR
  &error_code=ITEM_LOGIN_REQUIRED
  &error_message=the%20credentials%20were%20not%20correct
  &exit_status
  &institution_id=ins_55
  &institution_name=HSBC
  &institution_search_query=h
  &mfa_type
  &view_name=ERROR
  &request_id
  &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7
  ×tamp=2018-10-05T15%3A22%3A50.542Z
```

\=\*=\*=\*=

#### OAuth 

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) .

\=\*=\*=\*=

#### Supported platforms 

Plaid officially supports WKWebView on iOS 10 or later and Chrome WebView on Android 4.4 or later.

---


# Monitor - Watchlists and matching algorithms | Plaid Docs

Watchlists and Matching Algorithms 
===================================

#### Learn about the watchlists and matching algorithms used by Monitor 

Plaid Monitor's system supports a wide variety of algorithms and languages to support common inconsistencies across both user inputs and underlying watchlist search data.

#### Supported languages 

|  |  |  |
| --- | --- | --- |
| Arabic | German | Korean |
| Spanish | Simplified Chinese | Greek |
| Pashto | Thai | Traditional Chinese |
| Hungarian | Persian | Urdu |
| English | Italian | Portuguese |
| French | Japanese | Russian |
| Hebrew | Burmese | Vietnamese |

#### Supported algorithms 

|  |  |
| --- | --- |
| Phonetic similarity | Jesus ↔ Heyzeus ↔ Haezoos |
| Transliteration spelling differences | Abdul Rasheed ↔ Abd al-Rashid |
| Nicknames | William ↔ Will ↔ Bill ↔ Billy |
| Missing spaces or hyphens | MaryEllen ↔ Mary Ellen ↔ Mary-Ellen |
| Titles and honorifics | Dr. ↔ Mr. ↔ Ph.D. |
| Truncated name components | McDonalds ↔ McDonald ↔ McD |
| Missing name components | Phillip Charles Carr ↔ Phillip Carr |
| Out-of-order name components | Diaz, Carlos Alfonzo ↔ Carlos Alfonzo Diaz |
| Initials | J. E. Smith ↔ James Earl Smith |
| Names split inconsistently across database fields | Dick. Van Dyke ↔ Dick Van . Dyke |
| Same name in multiple languages | Mao Zedong ↔ Мао Цзэдун ↔ 毛泽东 ↔ 毛澤東 |
| Semantically similar names | Eagle Pharmaceuticals, Inc. ↔ Eagle Drugs, Co. |
| Semantically similar names across language | Nippon Telegraph and Telephone Corporation ↔ 日本電信電話株式会社 |

##### Name sensitivity 

Plaid determines a similarity score based on the result of these comparisons. Each type of matching will have a different impact on the overall similarity score, based on the importance of the discrepancy, the length and composition of the name being verified, and other variables like language. For example, "Mr. John Doe" vs. "John Doe" will receive a negligible penalty, whereas "John Paul Doe" vs "John Doe" will receive a more significant penalty.

The sensitivity you select will determine the minimum similarity score required for a match. We recommend that you start with Balanced sensitivity and adjust as needed.

If you are migrating from another identity verification solution and have configured similarity scores there, you can use the following table to roughly equate Plaid's sensitivity levels with similarity scores:

| Name sensitivity | Minimum acceptable similarity score |
| --- | --- |
| Coarse | 70 |
| Balanced | 80 |
| Strict | 90 |
| Exact | 100 |

Note that setting the scores at a comparable level between different solutions will not yield exactly the same results, since different products use different algorithms.

#### Supported watchlists 

**US – Office of Foreign Assets Control**

*   Specially Designated Nationals List
*   Foreign Sanctions Evaders
*   Palestinian Legislative Council
*   Sectoral Sanctions Identifications
*   Non-SDN Menu-Based Sanctions
*   Correspondent Account or Payable-Through Account Sanctions
*   Non-SDN Chinese Military-Industrial Complex List

**US - Department of Justice**

*   FBI Wanted List

**US – Department of State**

*   Nonproliferation Sanctions
*   AECA Debarred

**Bureau of Industry and Security**

*   Denied Persons List
*   Unverified List

**UK – Her Majesty’s Treasury**

*   Consolidated list

**EU – European External Action Service**

*   Consolidated list

**AU – Department of Foreign Affairs and Trade**

*   Consolidated list

**CA – Government of Canada**

*   Consolidated List of Sanctions

**International**

*   Interpol Red Notices for Wanted Persons List
*   World Bank Listing of Ineligible Firms and Individuals
*   United Nations Consolidated Sanctions

**Politically Exposed Persons**

*   Politically Exposed Persons List
*   State Owned Enterprise List
*   CIA List of Chiefs of State and Cabinet Members

**SG - Government of Singapore**

*   Terrorists and Terrorist Entities

**TR - Government of Turkey**

*   Terrorist Wanted List
*   Domestic Freezing Decisions
*   Foreign Freezing Requests
*   Weapons of Mass Destruction
*   Capital Markets Board

---


# Monitor - Introduction to Monitor | Plaid Docs

Introduction to Monitor  
=========================

#### Sanction, PEP, and watchlist screening for anti-money laundering compliance 

Get started with Monitor

[API Reference](https://plaid.com/docs/api/products/monitor/index.html.md) [Get started](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access)

#### Overview 

Monitor detects if your customers are on government watchlists, using modern APIs that reduce false positives and increase efficiency. Monitor screens users against a number of sanction and PEP lists. Sanction lists are updated daily and can be used for daily automated re-scans. Any hits will be exposed via both a user-friendly dashboard UI and via API, for use with either manual or automated review workflows. Monitor also integrates directly with [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) for an end-to-end verification and KYC solution.

Monitor can be used to screen end users in any country. To integrate with Monitor, your company must be based in the US or Canada.

[Watch video](https://www.youtube.com/watch?v=uzpg75DZ28Q)

#### Creating a program 

Monitor is not available by default in the Sandbox environment. To obtain Sandbox access, [request full Production access for Monitor](https://dashboard.plaid.com/settings/team/products) , which will automatically grant Sandbox access, or [contact Sales](https://plaid.com/products/monitor/#contactForm) . To obtain Sandbox access for Monitor if you are already using another Plaid product, you can also contact your account manager or submit an [access request ticket](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) .

The first step to integrating is logging into the dashboard and accessing the **New Program** page. Programs help you to define the settings and workflows for conducting watchlist screenings in your organization. For example, you can define match sensitivities, which lists are being screened, and the behavior of ongoing screening. For more details on the configuration of screenings and how matches are determined, see [Watchlists and Matching Algorithms](https://plaid.com/docs/monitor/algorithms-and-lists/index.html.md) .

Monitor allows you to start a customer in one program and then move them to a different one. To move users between programs, call [/watchlist\_screening/individual/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualupdate) or [/watchlist\_screening/entity/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityupdate) with the `watchlist_screening_id` you want to move and the ID of the program you want to move it to in the `watchlist_program_id` field. Customers cannot be in multiple programs at once.

The number of programs you wish to maintain will vary based on the complexity of your organization. Many companies choose to split up programs such that each program aligns to the compliance ownership within their organization and each reviewer will only see programs they are responsible for. Some common ways of splitting up programs are by product vertical ("Cardholders", "Personal Loans", "FDIC Accounts", etc.), geography ("US Cardholders", "European Cardholders", etc.), risk level ("High Risk Individuals", "Medium Risk Individuals"), or a combination of the above. For ideas about how to split customers up by risk, [OFAC has prepared a helpful risk matrix](https://cognitohq.com/blog/ofac-risk-matrix) that can provide a baseline for setting initial risk level and then modifying the risk level based on ongoing user behavior. You are allowed to change a program after it has been created, although note that increasing the sensitivity of a program after creation may result in a large influx of new hits.

If your use case involves an ongoing relationship with your customers, Plaid recommends creating at least two programs -- one with rescan enabled for active customers, and one with rescan disabled, for customers who have not yet established an ongoing relationship (for example, customers who have not completed the onboarding experience) or who have closed their accounts. For more details, see [Monitor fee model](https://plaid.com/docs/account/billing/index.html.md#monitor-fee-model) .

Once your first program is created, you can start your integration.

#### Basic integration overview 

Before integrating Monitor, make sure you have [Created a program](https://plaid.com/docs/monitor/index.html.md#creating-a-program) .

This integration overview describes the process for using a Dashboard-based review workflow, which is the most common way to use Monitor. The review process can also be performed using the API; see the [API reference](https://plaid.com/docs/api/products/monitor/index.html.md) for details.

If you are already using Plaid's [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) product:

1.  In the Identity Verification template editor, on the Setup tab, enable the **Screen customers** setting to automatically assign users to a Monitor program after they have completed verification.
2.  When your user has successfully completed the Identity Verification process, the response you receive from calling [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) will include a `watchlist_screening_id` value.
3.  Call [/watchlist\_screening/entity/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityget) or [/watchlist\_screening/individual/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualget) with this value, and check the `status` flag on the response.
    *   If it is `cleared`, your customer did not appear on any of your target screening lists.
    *   If it is `pending_review`, your customer received one or more hits and is pending review.
4.  For customers who are pending review, a member of your team will need to review and update the user's status in the Dashboard. When they do (and you have configured your webhooks as [described below](https://plaid.com/docs/monitor/index.html.md#configuring-webhooks) ) you will receive a webhook, `SCREENING: STATUS_UPDATED` (or `ENTITY_SCREENING: STATUS_UPDATED` for entities). This webhook will include the watchlist screening id of the individual.
5.  You can then make an additional call to [/watchlist\_screening/entity/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityget) or [/watchlist\_screening/individual/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualget) and check the `status` flag on the response.
    *   If it is `cleared`, the screening hit has been dismissed by a reviewer as invalid.
    *   If it is `pending_review`, a customer that was previously marked as `cleared` or `rejected` was marked for review.
    *   If it is `rejected`, your customer received a hit that has been confirmed by a reviewer as a valid match.

If you are not using Identity Verification, the process is slightly different:

1.  Create a customer object using [/watchlist\_screening/individual/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualcreate) or [/watchlist\_screening/entity/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitycreate) , passing along any verified information you have about your user. While not required, it is recommended to specify a `client_user_id`, which should refer to an internal ID in your database, to help associate this screening with your customer in the future.
2.  The results of this `create` call will include a `status` flag -- either `cleared`, or `pending_review` as specified above.
3.  At this point, you can proceed from step 4 in the above workflow.

#### Configuring webhooks 

To complete your integration, you should add a webhook receiver endpoint to your application.

Like Identity Verification, you can configure the webhooks sent by Monitor by visiting the dashboard [webhook configuration](https://dashboard.plaid.com/developers/webhooks) page. Click **New webhook**, and then select which events you want to subscribe to. For Monitor, there are two:

*   [SCREENING: STATUS\_UPDATED](https://plaid.com/docs/api/products/monitor/index.html.md#screening-status_updated) when an individual's screening status has been updated
*   [ENTITY: STATUS\_UPDATED](https://plaid.com/docs/api/products/monitor/index.html.md#entity_screening-status_updated) when an entity's screening status has been updated

Enter the URL of your webhook receiver for the webhook you wish to subscribe to and click **Save**. Plaid will now send an HTTP POST request to the webhook receiver endpoint every time the event occurs.

For more information on webhooks, see the [webhook documentation](https://plaid.com/docs/api/webhooks/index.html.md) .

#### Building a reviewer workflow 

This guide assumes that you will be using the dashboard for reviewing hits, but you can also re-create any aspect of the dashboard in your internal applications via the [API](https://plaid.com/docs/api/products/monitor/index.html.md) .

(An image of "Plaid Monitor Dashboard showing programs list with status, type, sensitivity, and monitoring options. Buttons for new programs.")

##### Assigning hits to reviewers 

Once your basic integration is complete, any customers who have potential hits will start showing up on your dashboard. You can assign any screenings that are pending review to different reviewers in your organization. If using an API-based review workflow, you can get a full list of users and their associated user IDs by calling [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) and setting your screening `assignee` to the desired reviewer.

#### Preparing for ongoing screening 

Monitor updates screening lists daily and supports ongoing daily rescans of your entire customer base to alert you when new hits are discovered. This system is designed around the concept of a living `pending_review` queue that is updated whenever new hits are found. We recommend that a reviewer log in daily to check the review status on the dashboard. If you prefer to be alerted when a hit is found or to handle hits via automation, you can set up a daily automated job to check [/watchlist\_screening/individual/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhitlist) or [/watchlist\_screening/entity/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhitlist) once a day to poll any of the screenings that end up in this queue. Then use the associated `client_user_id` or `id` to tie the hit back to your internal database and determine if action is required.

Plaid will also fire [webhooks](https://plaid.com/docs/api/products/monitor/index.html.md) to alert you when any new hits are found. Webhooks will contain the watchlist screening id, which you can use to go retrieve any watchlist screening hits that are pending review.

#### Generating reports 

You can generate and export reports on Monitor activity via the Dashboard, under [Monitor->Reports](https://dashboard.plaid.com/monitor/reports) . Reports are provided in .csv format.

You can also generate reports using the Monitor API. For example, you can use [/watchlist\_screening/individual/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividuallist) or [/watchlist\_screening/entity/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitylist) to generate the list of individuals or entities you'd like to report on, then call [/watchlist\_screening/individual/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhitlist) or [/watchlist\_screening/entity/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhitlist) for each target individual or entity to generate a list of their hits.

#### Additional considerations 

*   Adding Monitor is not the only part of a successful Anti-Money Laundering program. We highly recommend that you consult with an AML professional to help you build all of the policies and procedures required. AML regulations vary widely for different jurisdictions and industries.
*   Monitor **does not blanket ban any countries on your behalf**. Some sanction programs effectively prohibit working with certain jurisdictions and it is up to you to ensure that you are only working with individuals from countries that are appropriate for your desired risk levels. For instance, here is an [article from OFAC about a "Country List"](https://www.treasury.gov/resource-center/sanctions/Programs/Pages/faq_10_page.aspx)
*   Monitor is built to make it difficult to overconstrain a search and therefore have false negatives. That being said, if your data inputs are not quality controlled to at least a basic extent, this can result in false negatives or false positives (for example, broad searches based on incomplete names).

#### Testing Monitor 

Monitor is not available by default in the Sandbox environment. To obtain Sandbox access, [request full Production access for Monitor](https://dashboard.plaid.com/settings/team/products) , which will automatically grant Sandbox access, or [contact Sales](https://plaid.com/products/monitor/#contactForm) . To obtain Sandbox access for Monitor if you are already using another Plaid product, you can also contact your account manager or submit an [access request ticket](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) .

Sandbox supports a real-world dataset, meaning that sanctioned individuals should show up just as they would in Production. Some example sanctioned individuals and entities you can use for testing purposes include:

| Individual Name | Date of Birth | Location | Document |
| --- | --- | --- | --- |
| Joseph Kony | 1964-09-18 | CF |  |
| Jianshu Zhou | 1971-07-15 | CN | E09598913 |
| Ermias Ghermay | Any day in 1980 | LY |  |

| Entity Name | Location | Document |
| --- | --- | --- |
| Iran Mobin Electronic Development Company | IR | 10103492170 |
| МИНСКИЙ ОТРЯД МИЛИЦИИ ОСОБОГО НАЗНАЧЕНИЯ | BY |  |
| Islamic Radio And Television Union | AF |  |

Testing Monitor alongside Identity Verification can be a little tricky, as Monitor screens against a real-world dataset, while Identity Verification only supports one single test identity, Leslie Knope. If you wish to test the case of Identity Verification succeeding, but a Monitor screening encountering a hit, you can try one of these options:

*   From the Monitor section of the Dashboard, select the user from the **Cleared** tab and change their status from "Cleared" to "Pending Review" or "Rejected". This will fire a `STATUS_UPDATED` webhook, and the user's new screening status will be reflected in the response the next time you call [/watchlist\_screening/individual/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualget) .
*   You can also create additional watchlist screenings against the same client user ID by calling [/watchlist\_screening/individual/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualcreate) with the name and birthday of a real sanctioned individual. This screening will appear in the Monitor dashboard in the "Pending review" section and will be included in the array of screening results that get returned if you call [/watchlist\_screening/individual/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividuallist) with this client user ID.

Note that the Sandbox environment sanction and watchlist dataset may be out of date. Make sure all real checks are carried out on the live Production environment.

#### Additional resources 

For a step-by-step walkthrough of implementing Monitor, see the [Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf)

#### Monitor pricing 

Monitor has a base fee for each new user scanned, as well as a separate rescanning fee, determined by the number of users rescanned each month. For more details, see the [Monitor fee model](https://plaid.com/docs/account/billing/index.html.md#monitor-fee-model) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) .

#### Next steps 

To learn more about building with Monitor, see the [Monitor API Reference](https://plaid.com/docs/api/products/monitor/index.html.md) .

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Payments (Europe) | Plaid Docs

Introduction to Payments (Europe)  
===================================

#### Initiate real-time payments for account funding and transfers 

Get started with Payments (Europe)

[API Reference](https://plaid.com/docs/api/products/payment-initiation/index.html.md) [Integration Guide](https://plaid.com/docs/payment-initiation/add-to-app/index.html.md)

#### Overview 

Plaid's European Payments suite enables your users to make real-time payments without manually entering their account details or leaving your app. Common use cases include:

*   **Account funding:** Allow users to easily transfer money into your app or wallet.
*   **Pay-by-bank:** Payments supports both one-time payments and (in the UK) recurring payments. Accept payments, track settlement, and issue refunds.
*   **Payouts:** Pay out stored balances to your end users.

(An image of "Plaid Link payment flow: view payment details, select bank, authenticate with Gingham Bank, confirm payment with details.")

Benefits of Payments include:

*   **Easy integration with a single API:** Verify user accounts, manage risk, and move money across 20 markets, all through a single Plaid integration.
*   **Real-time settlement, simplified reconciliation:** Sweep transaction funds into your treasury account quickly and balance your books with an intuitive reconciliation report.
*   **Multi-rail support:** Payments supports Faster Payments Service (FPS), SEPA Instant Credit Transfer, SEPA Credit Transfer and local country payment rails. Easily switch payment rails with a single request parameter, no complex code changes required.
*   **Streamlined operational support:** Manage daily operations with the Plaid Dashboard to easily monitor payment activity.

For enhanced capabilities, you can add the optional [Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) feature to unlock advanced features such as sending refunds to users, allowing your users to payout a credit balance to a bank account, or gaining granular visibility into the settlement status of a payment.

Payments is Europe-only. Looking for similar capabilities in the US? Check out the [Transfer](https://plaid.com/docs/transfer/index.html.md) docs.

#### Payments solutions 

The Payments suite includes the following solutions. You can "mix and match" these solutions, incorporating all three for a robust, fully-integrated solution, or purchase them separately, incorporating only the ones you need. (Exception: Payouts requires Virtual Accounts and cannot be used separately.)

**[One-time Payment Initiation](https://plaid.com/docs/payment-initation/payment-initiation-one-time/index.html.md)** : Enable your users to make single real-time payments, such as SEPA Instant Credit Transfers or Single Immediate Payments (UK), without manually entering their account number and sort code.

**[Variable Recurring Payments (VRP)](https://plaid.com/docs/payment-initiation/vrp/index.html.md)** _(UK only)_: Establish a single recurring payment consent, which can then be used for a series of ongoing payments, with no end user interaction required. For background information on what Variable Recurring Payments (VRPs) are and how they work in the UK banking system, see the [Plaid VRP FAQ](https://support.plaid.com/hc/en-us/articles/24622039958295-What-are-Variable-Recurring-Payments-VRPs) . For instructions on integrating support for Variable Recurring Payments using Plaid, see [Add Variable Recurring Payments to your app](https://plaid.com/docs/payment-initiation/vrp/index.html.md) .

**[Payouts](https://plaid.com/docs/payment-initiation/virtual-accounts/payouts/index.html.md)** (requires Virtual Accounts add-on): Payouts enables users to seamlessly and instantly make withdrawals or get paid.

Any of the solutions above can also be enhanced with the Virtual Accounts add on:

**[Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md)** : Collect payments, get confirmation when payments settle, initiate payouts and refunds, and streamline reconciliation processes. Virtual Accounts provides granular control and visibility throughout the entire lifecycle of a payment.

Payments can also be used with other Plaid solutions such as [Auth](https://plaid.com/docs/auth/index.html.md) , [Identity](https://plaid.com/docs/identity/index.html.md) , [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , and [Monitor](https://plaid.com/docs/monitor/index.html.md) for enhanced anti-fraud protections and KYC/AML compliance.

#### Onboarding and account funding integration guide 

See [User onboarding and account funding](https://plaid.com/docs/payment-initiation/user-onboarding-and-account-funding/index.html.md) for an implementation guide to using Plaid's Europe Payments suite as part of a KYC and AML compliant onboarding flow.

---


# Payments (Europe) - Add Payment Initiation to your app | Plaid Docs

Add One-Time Payment Initiation to your app 
============================================

#### Learn how to use one-time Payment Initiation in your application 

In this guide, we start from scratch and walk through how to set up a one-time [Payment Initiation](https://plaid.com/docs/api/products/payment-initiation/index.html.md) flow. For a high-level overview of all our payment related offerings, see the [Introduction to Payments (Europe)](https://plaid.com/docs/payment-initiation/index.html.md) .

For an example guide to using one-time Payment Initiation as part of an integrated onboarding flow with other Plaid products, see [Onboarding and account funding guide](https://plaid.com/docs/payment-initiation/one-time-payment-initiation/user-onboarding-and-account-funding/index.html.md) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) , and must be completed before connecting to certain institutions.

#### Access Payment Initiation 

Payments (Europe) is enabled in Sandbox by default. It uses test data and does not interact with financial institutions. You may need to request access to Payment Initiation via the [Dashboard](https://dashboard.plaid.com) before using it in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### One-time Payment Initiation flow overview 

Before we jump into the code, let's see an overview of the steps needed to set up your payment with Plaid:

**1**Your app collects information of the sender and the recipient, as well as the payment amount.

(An image of "Step 1 diagram")

**2**With this information, [create a recipient](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) and obtain a `recipient_id`. You can reuse this `recipient_id` for future payments.

(An image of "Step 2 diagram")

**3**Provide the `recipient_id` to Plaid when you [create a payment](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) . Store the resulting `payment_id` along with your payment metadata.

(An image of "Step 3 diagram")

**4**From your backend, use the `payment_id` to [create a link\_token](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

(An image of "Step 4 diagram")

**5**Your client app uses the `link_token` to initiate a Link flow for your user. The onSuccess callback signals that the payment has been initiated.

(An image of "Step 5 diagram")

**6**Your backend listens for [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhooks to keep track of the payment's status.

(An image of "Step 6 diagram")

##### Create a recipient 

Before beginning the payment initiation process, you will need to know the name and account information of the recipient. With this information in hand, you can then call [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) to create a payment recipient and receive a `recipient_id`. You can later reuse this `recipient_id` for future payments to the same account.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { PaymentInitiationRecipientCreateRequest } = require('plaid');


// Using BACS, without IBAN or address
const request: PaymentInitiationRecipientCreateRequest = {
  name: 'John Doe',
  bacs: {
    account: '26207729',
    sort_code: '560029',
  },
};
try {
  const response = await plaidClient.paymentInitiationRecipientCreate(request);
  const recipientID = response.data.recipient_id;
} catch (error) {
  // handle error
}
```

##### Create a payment 

Now that you have the `recipient_id`, you can provide it together with the payment amount to [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) , which returns a `payment_id`.

Select group for content switcher

Current librariesLegacy libraries

```javascript
const { PaymentInitiationPaymentCreateRequest } = require('plaid');


const request: PaymentInitiationPaymentCreateRequest = {
  recipient_id: recipientID,
  reference: 'TestPayment',
  amount: {
    currency: 'GBP',
    value: 100.0,
  },
};
try {
  const response = await plaidClient.paymentInitiationPaymentCreate(request);
  const paymentID = response.data.payment_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

Make sure to store the `payment_id` in your backend together with your own metadata (e.g. your internal `user_id`). You can use this later to process the [payment status updates](https://plaid.com/docs/api/products/payment-initiation/index.html.md#webhooks)

##### Create a link\_token 

Before initializing Link, you need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you created. This will bring up the payment initiation flow in Link that allows your end user to confirm the payment.

When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to create a token for use with Payment Initiation, you provide the `payment_id` and specify `payment_initiation` as the product.

While it is possible to initialize Link with many products, `payment_initiation` cannot be specified along with any other products and must be the only product in Link's product array if it is being used.

In the code samples below, you will need to replace `PLAID_CLIENT_ID` and `PLAID_SECRET` with your own keys, which you can get from the [Dashboard](https://dashboard.plaid.com/developers/keys) .

Select group for content switcher

Current librariesLegacy libraries

```javascript
// Using Express
app.post('/api/create_link_token', async function (request, response) {
  const configs = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: 'user-id',
    },
    client_name: 'Plaid Test App',
    products: [Products.PaymentInitiation],
    language: 'en',
    webhook: 'https://webhook.sample.com',
    country_codes: [CountryCode.Gb],
    payment_initiation: {
      payment_id: paymentID,
    },
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(configs);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

Once you have exposed an endpoint to create a `link_token` in your application server, you now need to configure your client application to import and use Link.

#### Launch the payment initiation flow in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for the many financial institutions that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Because Link has access to all the details of the payment at the time of initialization, it will display a screen with the payment details already populated. All your end user has to do is log in to their financial institution through a Link-initiated OAuth flow, select a funding account, and confirm the payment details.

(An image of "Plaid Link payment flow: View payment details, select bank, authenticate with bank, payment confirmation with bank and transaction info.")

Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

##### Install Link dependency 

```jsx

  Link for Payment Initiation
  

```

##### Configure the client-side Link handler 

Plaid communicates to you certain events that relate to how the user is interacting with Link. What you do with each of these event triggers depends on your particular use case, but a basic scaffolding might look like this:

```javascript
const linkHandler = Plaid.create({
  // Create a new link_token to initialize Link
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Show a success page to your user confirming that the
    // payment will be processed.
    //
    // The 'metadata' object contains info about the institution
    // the user selected.
    // For example:
    //  metadata  = {
    //    link_session_id: "123-abc",
    //    institution: {
    //      institution_id: "ins_117243",
    //      name:"Monzo"
    //    }
    //  }
  },
  onExit: (err, metadata) => {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior to exiting.
    }
    // 'metadata' contains information about the institution
    // that the user selected and the most recent API request IDs.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect with Plaid.
    // For example:
    //  eventName = "TRANSITION_VIEW",
    //  metadata  = {
    //    link_session_id: "123-abc",
    //    mfa_type:        "questions",
    //    timestamp:       "2017-09-14T14:42:19.350Z",
    //    view_name:       "MFA",
    //  }
  },
});


linkHandler.open();
```

Unlike other products, for `payment_initiation` it is not necessary to exchange the `public_token` for an `access_token`. You only need the `payment_id` to interact with the `payment_initiation` endpoints.

#### Verify payment status 

##### Listening for status update webhooks 

Once the payment has been authorised by the end user and the Link flow is completed, the `onSuccess` callback is invoked, signaling that the payment status is now `PAYMENT_STATUS_INITIATED`.

From this point on, you can track the payment status using the [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhook that is triggered by Plaid when updates occur:

*   Updates are sent by Plaid to the [configured webhook URL](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-webhook) to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a [webhook\_type](https://plaid.com/docs/api/products/payment-initiation/index.html.md#PaymentStatusUpdateWebhook-webhook-type) of `PAYMENT_INITIATION`.
*   Once you receive the status update, use the [payment\_id](https://plaid.com/docs/api/products/payment-initiation/index.html.md#PaymentStatusUpdateWebhook-payment-id) field to retrieve the payment's metadata from your database.
*   From the status update object, use the [new\_payment\_status](https://plaid.com/docs/api/products/payment-initiation/index.html.md#PaymentStatusUpdateWebhook-new-payment-status) field to decide what action needs to be taken for this payment. For example, you may decide to fund the account once the payment status is `PAYMENT_STATUS_EXECUTED` or notify the user that their payment got rejected (`PAYMENT_STATUS_REJECTED`).

For more information, see [Payment Status](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) .

For more information on how to implement your webhook listener, see the [webhooks documentation](https://plaid.com/docs/api/webhooks/index.html.md) .

#### Sample code in Plaid Pattern 

For an example implementation of Payment Initiation, see the [Payment Initiation Pattern App](https://github.com/plaid/payment-initiation-pattern-app) on GitHub, which uses Payment Initiation in an account funding use case.

---


# Payments (Europe) - Handling failed payments | Plaid Docs

Handling failed payments 
=========================

#### Implement retry strategies and handle failures gracefully 

#### Retrying a payment 

To retry a failed payment, call [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) again with the same `recipient_id` and `amount`. Always ensure that retry logic doesn't create duplicate successful payments -- make sure to create a new payment with a new idempotency key to ensure the retry is processed as a separate transaction, and verify the status of previous attempts before initiating new ones.

If you have reached the limit for retry attempts, or the error is not immediately retryable, you should clearly explain the payment failure to your user and offer alternative payment methods or funding options.

#### Retryable payment failures 

The following failures are temporary and can be successfully retried.

**`PAYMENT_STATUS_FAILED`** is typically due to a transient issue, such as temporary network problems or bank system maintenance. If you experience this status, it is recommended to make one or two retry attempts immediately. Limit the number of retry attempts to avoid causing a negative customer experience.

**`PAYMENT_STATUS_BLOCKED`** indicates the payment was blocked by Plaid. This is typically due to regulatory or compliance reasons. Once the compliance issue is resolved, the payment can be retried.

**`PAYMENT_STATUS_INSUFFICIENT_FUNDS`** indicates the payment failed due to insufficient funds. Once the user has sufficient funds, the payment can be retried. If you experience this status, it is recommended to tell the user what happened and to give them the option to trigger a retry, or make a new payment, once they have added funds.

---


# Payments (Europe) - Payment Initiation | Plaid Docs

Payment Initiation 
===================

#### Use Payment Initiation for one-time payments 

Get started with Payment Initiation

[API Reference](https://plaid.com/docs/api/products/payment-initiation/index.html.md) [Integration Guide](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/add-to-app/index.html.md) [Onboarding and account funding guide](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/user-onboarding-and-account-funding/index.html.md)

#### Payment Initiation 

Plaid's one-time Payment Initiation functionality enables your users to make secure, real-time payments without manually entering their account details or leaving your app. Perfect for account funding, marketplace transactions, or any single payment needs, one-time payments, also known in the UK as Single Immediate Payments, provide a faster, easier, and safer way to move money.

Benefits of Payment Initiation:

*   **Faster, easier, safer:** Real-time payments that boost revenue while reducing fraud and chargebacks with identity and bank account verification.
*   **Infrastructure built for scale:** Plaid handles the backend heavy lifting with instant notifications, seamless reconciliation, and real-time settlement across 20 markets.
*   **Multi-rail support:** Underpinned by Faster Payments Service (FPS), SEPA Instant Credit Transfer, SEPA Credit Transfer and local country payment rails. Easily decide the payment rails with a single setting, using the same integration code.

By combining one-time payments with the optional [Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) product, you can enable even more functionality, such as sending refunds to users, allowing your users to payout a credit balance to a bank account, or gaining granular visibility into the settlement status of a payment.

#### Integration details 

See the [Add Payment Initiation to your App](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/add-to-app/index.html.md) guide to learn more about the product and how to implement it using Plaid Link.

For a complete integration, you will need to [track payment status](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/payment-status/index.html.md) and [handle failed payments](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/handling-failed-payments/index.html.md) .

If you plan to implement refund capabilities, see [refunds](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/refunds/index.html.md) .

#### Sample app 

For a simple real-world implementation of Payment Initiation, see the [Payment Initiation Pattern App](https://github.com/plaid/payment-initiation-pattern-app) on GitHub, which uses Payment Initiation in an account funding use case.

#### Onboarding and account funding integration guide 

See [User onboarding and account funding](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/user-onboarding-and-account-funding/index.html.md) for an implementation guide to using Payment Initiation as part of a KYC and AML compliant onboarding flow.

#### Testing Payment Initiation 

Payments can immediately be tried out with test data in the Sandbox environment. In order to test payments against live Items in Production, you will need to first request access by [contacting Sales](https://plaid.com/contact) or your Account Manager.

When testing in [Limited Production](https://plaid.com/docs/sandbox/index.html.md#testing-with-live-data-using-limited-production) , payments must be below 5 GBP or other chosen [currency](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-create-request-amount-currency) . For details on any payment limits in full Production, contact your Plaid Account Manager.

#### Pricing 

Payment Initiation is billed on a [per-payment model](https://plaid.com/docs/account/billing/index.html.md#payment-initiation-fee-model) . To view the exact pricing you may be eligible for, [contact Sales](https://plaid.com/contact/) .

---


# Payments (Europe) - Payment Status | Plaid Docs

Payment Status 
===============

#### Verify payment status and track settlement using webhooks 

#### Tracking payment status 

Once the payment has been authorised by the end user and the Link flow is completed, the `onSuccess` callback is invoked, signaling that the payment status is now `PAYMENT_STATUS_AUTHORISING`.

From this point on, you can track the payment status using the [PAYMENT\_STATUS\_UPDATE webhook](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) , which Plaid sends to the [configured webhook URL](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-webhook) in real time to indicate that the status of an initiated payment has changed. (For more information on how to implement your webhook listener, see the [webhook documentation](https://plaid.com/docs/api/webhooks/index.html.md) ).

While you can repeatedly call [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) to check a payment's status instead of listening for webhooks, this approach may [trigger API rate limit errors](https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md) and is strongly discouraged. Only consider polling as a fallback when webhooks are unavailable or significantly delayed.

Once you receive the [PAYMENT\_STATUS\_UPDATE webhook](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) , use the [payment\_id](https://plaid.com/docs/api/products/payment-initiation/index.html.md#PaymentStatusUpdateWebhook-payment-id) field to retrieve the payment's metadata from your database.

From the status update object, use the [new\_payment\_status](https://plaid.com/docs/api/products/payment-initiation/index.html.md#PaymentStatusUpdateWebhook-new-payment-status) field to decide what action needs to be taken for this payment. For example, you may decide to fund the account once the payment status is `PAYMENT_STATUS_EXECUTED`, or display a user-facing error if the status is `PAYMENT_STATUS_REJECTED`.

Note: In order to protect against webhook forgery attacks, before funding an account in response to a webhook, it's recommended to ensure the status is legitimate. One way is to implement [webhook verification](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md) . An easier alternative is to verify the new status by calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) a single time after receiving the webhook.

#### Terminal payment statuses 

For many payments, including most payments in the UK, the terminal status (if not using Virtual Accounts) is `PAYMENT_STATUS_EXECUTED`, which indicates that funds have left the payer's account. `PAYMENT_STATUS_INITIATED` is the terminal state for payments at some non-UK banks, as well as smaller UK banks.

Funds typically settle (i.e., arrive in the payee's account) within a few seconds of the payment execution, although settlement of an executed payment is not guaranteed.

If using [Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/payment-confirmation/index.html.md) , the successful terminal status will always be `PAYMENT_STATUS_SETTLED`, regardless of bank.

To gain access to the `PAYMENT_STATUS_SETTLED` terminal status and track whether a payment has settled, you can use the [Payment Confirmation feature](https://plaid.com/docs/payment-initiation/virtual-accounts/payment-confirmation/index.html.md) , available via the [Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) product. To request access, contact your Account Manager.

##### Terminal payment status timeframes 

The most common payment schemes and their settlement times are:

*   **Faster Payments Service (FPS):** An instant payment scheme used in the UK. The money is usually available in the receiving customer's account almost immediately, although it can sometimes take up to two hours.
*   **SEPA Instant Credit Transfer:** A pan-European instant payment scheme. Funds will be made available in less than ten seconds.
*   **SEPA Credit Transfer:** A pan-European payment scheme where payments are processed and settled within one business day.

#### Payment status transitions 

Below is the status transitions for Payment Initiation. If using Virtual Accounts, see [Payment Confirmation](https://plaid.com/docs/payment-initiation/virtual-accounts/payment-confirmation/index.html.md) , which adds the `SETTLED` status.

```undefined
INPUT_NEEDED 
    |
    +--> AUTHORISING 
    |        |
    |        +--> INITIATED [terminal state for successful payments at some banks]
    |        |        |
    |        |        +--> EXECUTED [For some banks only, mostly in UK]
    |        |        |
    |        |        +--> BLOCKED 
    |        |        +--> REJECTED
    |        |        +--> CANCELLED
    |        |        +--> INSUFFICIENT_FUNDS
    |        |        +--> FAILED
    |        |
    |        +--> BLOCKED
    |
    +--> BLOCKED
```

---


# Payments (Europe) - Refunds | Plaid Docs

Refunds 
========

#### Handle refunds for Payment Initiation transactions 

#### Refunding payments 

For Payment Initiation (without Virtual Accounts), refunds can be executed using your banking partner to send funds to a user's bank account.

When calling [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) you can set `request_refund_details: true`. If you do, the refund details (account number and sort code) will be available in the `/payment/get` response. You can then use your banking partner to push a refund to the end-user requesting a refund. Support varies across financial institutions and will not always be available.

Alternatively, if you have used Plaid's [Auth](https://plaid.com/docs/auth/index.html.md) product for account verification before making a payment, you will also have access to the user's bank account details.

For streamlined refunds via Plaid, see [Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) .

---


# Payments (Europe) - User onboarding and account funding guide | Plaid Docs

User onboarding and account funding 
====================================

#### Use Plaid to simplify your onboarding and funding flow in Europe 

In this guide, we first walk through setting up an account linking flow that uses Plaid to connect your user's bank account. We'll then demonstrate how to verify the identity of your users which may help comply with KYC and AML regulations.

Finally, we’ll show how how to initiate payments while requiring that bank accounts involved in money movements are verified.

If you're looking for a guide that is specific to Plaid's One-Time Payment Initiation product and does not incorporate other features such as anti-fraud measures or Identity Verification, see [Add One-time Payment Initiation to your App](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md) .

This guide is specific to integrations serving end users in Europe (including non-EU countries such as the UK and Norway). For US payment solutions, see [Transfer](https://plaid.com/docs/transfer/index.html.md) .

#### Before you get started 

The [Auth](https://plaid.com/docs/auth/index.html.md) , [Identity](https://plaid.com/docs/identity/index.html.md) , and [Payments (Europe)](https://plaid.com/docs/payment-initiation/index.html.md) products covered in this guide can immediately be tried out in the Sandbox environment, which uses test data and does not interact with financial institutions.

To gain access to these products in the Production environments, [request product access](https://dashboard.plaid.com/settings/team/products) or [contact Sales](https://plaid.com/contact/) . If you already are using Plaid products, you can also request access by contacting your account manager or submitting a [Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

### User onboarding 

The **Plaid flow** begins when the user registers with your app. The flow will connect your app to your user's financial institution.

(An image of "Step diagram")

**1**Your backend creates a `link_token` by using the[/link/token/create](https://plaid.com/docs/api/link/index.html.md#create-link-token) endpoint and passes the temporary token to your Client app.

(An image of "Step 1 diagram")

**2**Your Client app uses the `link_token` to initiate a Link flow for your user. The [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) signals that the user has granted your app access to their financial institution.

(An image of "Step 2 diagram")

**3**The `onSuccess` payload contains a [public\_token](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-public-token) which, after sending it to your backend, needs to be exchanged for a long-lived access token using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint.

(An image of "Step 3 diagram")

**4**Using this access token your backend can now retrieve the user’s bank account numbers via [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or their identity information (such as their full name) via [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) .

(An image of "Step 4 diagram")

#### Adding the Auth and Identity products to your app 

The steps listed above are broken down into more detail in the guides linked below. The first guide covers adding the [Auth](https://plaid.com/docs/api/products/auth/index.html.md) product (e.g. for obtaining the user’s bank account numbers). The second covers the [Identity](https://plaid.com/docs/api/products/identity/index.html.md) product (e.g. for obtaining the user’s legal name). Both guides describe almost identical steps, so you can follow either one.

The next section will highlight the single difference between the two and will show how you can use both products at the same time.

#### Auth 

Add Auth to your app

[Detailed steps](https://plaid.com/docs/auth/add-to-app/index.html.md)

#### Identity 

Add Identity to your app

[Detailed steps](https://plaid.com/docs/identity/add-to-app/index.html.md)

#### Creating a Link token 

Link token creation is the only step requires changes when requesting both Auth and Identity-related information. To do so, pass both products as part of the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request.

```bash
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "client_name": "Plaid Test App",
  "user": { "client_user_id": "${UNIQUE_USER_ID}" },
  "products": ["auth", "identity"], // using both products
  "country_codes": ["GB", "NL", "DE"],
  "language": "en"
  "webhook": "https://webhook.sample.com",
}'
```

#### End user experience 

During the Link flow, your user grants permission to all the data products that you request. The images below demonstrate examples of the panes Link will present when requesting access to one or multiple products.

(An image of "Plaid consent screen for sharing financial data with WonderWallet, featuring an 'Allow' button and 'Account details' section.")

(An image of "Plaid data sharing consent screen, listing Contact and Account details. Buttons: Allow, Cancel. Terms link present.")

### Optional steps and best practices 

The sections below in this guide describe optional steps you can use to improve link conversion or achieve KYC/AML compliance.

#### Preselecting a financial institution 

By default, Plaid will ask the user to manually select their financial institution. However, there might be cases where you already know which institution your user wants to use. For example, when your user has previously completed a sign up flow, you can increase conversion by skipping this part of the payment flow. This requires two steps:

1.  Call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) with the `access_token` as an input parameter. This endpoint will return the [institution\_id](https://plaid.com/docs/api/items/index.html.md#item-get-response-item-institution-id) as part of the response.
2.  Provide the `institution_id` as part of the payment [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request.

```bash
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "client_name": "Plaid Test App",
  "user": { "client_user_id": "${UNIQUE_USER_ID}" },
  "products": ["payment_initiation"],
  "country_codes": ["GB", "NL", "DE"],
  "language": "en"
  "webhook": "https://webhook.sample.com",
  "payment_initiation": { "payment_id": "${PAYMENT_ID}" },
  "institution_id": "${INSTITUTION_ID}" // preselect institution_id
}'
```

#### Compliant account funding 

To help comply with KYC & AML regulations you may choose to restrict payments to your app from bank accounts whose owner was previously verified.

One-Time Payment Initiation can support this flow by requiring that a payment is to be made from a specific account. The process has three steps:

1.  Call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) with the `access_token` as an input parameter. This endpoint will return the user’s account numbers as part of the response (Use [bacs](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-numbers-bacs) for the UK and [international](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-numbers-international) for the rest of Europe).
2.  Provide one of the account numbers under [options](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-create-request-options) as part of the [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) request. See the snippet below as an example.
3.  Provide the `institution_id` as part of the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, as described in the previous section.

Not all financial institutions support this feature. In the UK there is full support. In the rest of Europe, support may be limited. Plaid will let the user choose any account when their financial institution does not support this feature. It is recommended to also verify the origin of payments as part of your payment reconciliation process.

```bash
curl -X POST https://sandbox.plaid.com/payment_initiation/payment/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "recipient_id": "${RECIPIENT_ID}",
  "reference": "Sample reference",
  "amount": {
    "currency": "GBP",
    "amount": 1.99
  },
  "options": { // additional payee account restriction
    "bacs": {
        "account": "26207729",
        "sort_code": "560029"
    }
  }
}'
```

#### Compliant withdrawals 

To comply with KYC and AML regulations, you may want to restrict outbound money movements to accounts whose owner is verified. You can do this in the following ways:

##### Using Virtual Accounts 

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see [Managing virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md) .

1.  Follow the [Payment Confirmation flow](https://plaid.com/docs/payment-initiation/virtual-accounts/payment-confirmation/index.html.md) to confirm that funds have settled in your virtual account.
2.  Fetch the payment object by calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) with the `payment_id` of the payment you initiated. The payment object will contain a [transaction\_id](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-get-response-transaction-id) , which corresponds to the payment's underlying virtual account transaction.
3.  Fetch the virtual account transaction by calling [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) with the `transaction_id`.
4.  The virtual account transaction will contain account details in the `counterparty` field.
5.  [Execute a Payout](https://plaid.com/docs/payment-initiation/virtual-accounts/payouts/index.html.md) using the `counterparty` details.

##### Using Auth data 

1.  Call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) with the `access_token` as an input parameter. This endpoint will return the user’s verified account numbers as part of the response (Use [bacs](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-numbers-bacs) for the UK and [international](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-numbers-international) for the rest of Europe).
2.  Select accounts that can receive funds by filtering for `account.subtype = "checking"`.
3.  Initiate the withdrawal to any of the filtered accounts. You may want to let the user choose a preferred account in case there are multiple.

##### Using the request\_refund\_details flag 

This approach is not recommended since it is an optional flag with limited incomplete coverage dependent on the financial institution a payment was initiated to.

1.  Go through the [One-Time Payment Initiation flow](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md) and initiate a payment with the [request\_refund\_details](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-create-request-options-request-refund-details) flag enabled.
2.  Fetch the payment object by calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and parse the [refund\_details](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-get-response-refund-details) field.
3.  Initiate the withdrawal to account specified in the `refund_details` field.

---


# Payments (Europe) - Account Sweeping | Plaid Docs

Account Sweeping 
=================

#### Sweep funds from your virtual account 

Account sweeping periodically sweeps the current balance of a virtual account to a designated client-owned bank account. By default, automated account sweeping is not enabled.

Sweeping funds ensures you control how much balance you maintain in your virtual account. If a virtual account used for refunds or payouts also has account sweeping enabled, there may be requests that fail whenever a virtual account does not have sufficient funds.

#### Sweep funds from a Virtual Account 

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see [Managing virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md) .

There are two ways you can sweep funds from your virtual account:

##### (Preferred) Automated 

For each virtual account you want automated account sweeping to be enabled for, provide your Account Manager with:

*   The virtual account's `wallet_id`.
    
*   The account details for the designated account which funds should be swept to.
    

The current balance of each virtual account will be swept once a day at 12:00AM UTC indefinitely.

##### Manual 

If you prefer to manually control account sweeping, you will need to manually [execute a Payout](https://plaid.com/docs/payment-initiation/virtual-accounts/payouts/index.html.md) each time you want to sweep funds.

---


# Payments (Europe) - Add Virtual Accounts to your app | Plaid Docs

Add Virtual Accounts to your app 
=================================

#### Use virtual accounts to gain additional insight and control over the flow of funds 

In this guide, we'll walk through how to set up and manage virtual accounts. After integrating you will be able to send and receive money, make withdrawals and refunds, and reconcile funds for faster reconciliation.

Note: The Sandbox environment uses test data and does not interact with financial institutions.

#### Integrate with Plaid Payment Initiation and enable Virtual Accounts 

Virtual accounts are designed to be used in conjunction with the Payment Initiation APIs. To get the most out of Plaid virtual accounts, first [add Payment Initiation to your app](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md) . In order to be enabled for Virtual Accounts in Production, contact your Account Manager. To test in Sandbox, begin by creating a virtual account via [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) .

```javascript
const request: WalletCreateRequest = {
  iso_currency_code: isoCurrencyCode,
};
try {
  const response = await plaidClient.walletCreate(request);
  const walletID = response.data.wallet_id;
  const balance = response.data.balance;
  const numbers = response.data.numbers;
  const recipientID = response.data.recipient_id;
} catch (error) {
  // handle error
}
```

#### Enable Virtual Account Transaction webhooks 

Enable [virtual account webhooks](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md#webhooks) to receive notifications when new transaction events occur. Plaid will send a webhook for each transaction event. These notifications can be used to stay updated on transaction status information.

#### Funding your Virtual Account through Payment Initiation 

##### Create a Payment that will be initiated to your virtual account 

```javascript
const request: PaymentInitiationPaymentCreateRequest = {
  recipient_id: recipientID,
  reference: 'TestPayment',
  amount: {
    currency: 'GBP',
    value: 100.0,
  },
};
try {
  const response = await plaidClient.paymentInitiationPaymentCreate(request);
  const paymentID = response.data.payment_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

Use the `recipient_id` associated with your `wallet_id` so Plaid knows to route the payment to your virtual account.

##### Launch and complete the Payment Initiation flow in Link 

For more details on how to do this, see the [Payment Initiation documentation](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md#launch-the-payment-initiation-flow-in-link) .

##### Confirm that the payment has settled via a payment webhook 

For more details, see the [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhook.

```json
{
  "webhook_type": "PAYMENT_INITIATION",
  "webhook_code": "PAYMENT_STATUS_UPDATE",
  "payment_id": "",
  "new_payment_status": "PAYMENT_STATUS_SETTLED",
  "old_payment_status": "PAYMENT_STATUS_EXECUTED",
  "original_reference": "Account Funding 99744",
  "adjusted_reference": "Account Funding 99",
  "original_start_date": "2017-09-14",
  "adjusted_start_date": "2017-09-15",
  "timestamp": "2017-09-14T14:42:19.350Z"
}
```

##### Confirm that funds have arrived in your virtual account via a transaction webhook 

For more details, see the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook.

```json
{
  "webhook_type": "WALLET",
  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
  "wallet_id": "",
  "new_status": "SETTLED",
  "old_status": "INITIATED",
  "timestamp": "2021-09-14T14:42:19.350Z"
}
```

#### Executing a Payout 

##### Fetch your virtual account to confirm it has sufficient balance 

```javascript
const request: WalletGetRequest = {
  wallet_id: walletID,
};
try {
  const response = await plaidClient.walletGet(request);
  const walletID = response.data.wallet_id;
  const balance = response.data.balance;
  const numbers = response.data.numbers;
} catch (error) {
  // handle error
}
```

##### Execute a payout 

```javascript
const request: WalletTransactionExecuteRequest = {
  wallet_id: walletID,
  counterparty: {
    name: 'Test',
    numbers: {
      bacs: {
        account: '12345678',
        sort_code: '123456',
      },
    },
  },
  amount: {
    value: 1,
    iso_currency_code: 'GBP',
  },
  reference: 'transaction ABC123',
  idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753',
};
try {
  const response = await plaidClient.walletTransactionExecute(request);
  const transactionID = response.data.transaction_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

##### Confirm the payout was executed, via a transaction webhook 

For more details, see the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook.

```json
{
  "webhook_type": "WALLET",
  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
  "wallet_id": "",
  "new_status": "EXECUTED",
  "old_status": "INITIATED",
  "timestamp": "2021-09-14T14:42:19.350Z"
}
```

#### Refunding a Payment Initiation payment 

##### Fetch your virtual account to confirm it has sufficient balance 

```javascript
const request: WalletGetRequest = {
  wallet_id: walletID,
};
try {
  const response = await plaidClient.walletGet(request);
  const walletID = response.data.wallet_id;
  const balance = response.data.balance;
  const numbers = response.data.numbers;
} catch (error) {
  // handle error
}
```

##### Refund a Payment Initiation payment 

```javascript
const request: PaymentInitiationPaymentReverseRequest = {
  payment_id: paymentID,
  reference: 'Refund for purchase ABC123',
  idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912',
};
try {
  const response = await plaidClient.paymentInitiationPaymentReverse(request);
  const refundID = response.data.refund_id;
  const status = response.data.status;
} catch (error) {
  // handle error
}
```

##### Confirm the refund was executed, via a transaction webhook 

For more details, see the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook.

```json
{
  "webhook_type": "WALLET",
  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
  "wallet_id": "",
  "new_status": "EXECUTED",
  "old_status": "INITIATED",
  "timestamp": "2021-09-14T14:42:19.350Z"
}
```

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Payments (Europe) - Virtual Accounts and Payouts | Plaid Docs

Introduction to Virtual Accounts  
==================================

#### Manage the entire lifecycle of a payment 

Get started with Virtual Accounts

[API Reference](https://plaid.com/docs/api/products/virtual-accounts/index.html.md) [Getting Started Guide](https://plaid.com/docs/payment-initiation/virtual-accounts/add-to-app/index.html.md)

#### Overview 

Plaid's virtual account API allows you to collect domestic payments, initiate payouts and refunds, and streamline reconciliation processes. Virtual accounts provide granular control and visibility throughout the entire lifecycle of a payment. Virtual accounts can be used independently, or can layered on top of Payments functionality to provide insight into the settlement status of all transactions, pay out to your merchants, allow end users to withdraw their funds, and issue refunds.

For example, if you have a brokerage app, you can use [One-Time Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) for end users to fund their accounts. [Payment Confirmation](https://plaid.com/docs/payment-initiation/virtual-accounts/payment-confirmation/index.html.md) will inform you when your end users' payments have settled so you can release these funds for your end users to purchase equities. When your end users sell their equity purchases, you can use [Payouts](https://plaid.com/docs/payment-initiation/virtual-accounts/payouts/index.html.md) to let them cash out their earnings.

See the [Add Virtual Accounts to your App](https://plaid.com/docs/payment-initiation/virtual-accounts/add-to-app/index.html.md) guide to learn more about how to implement virtual accounts.

#### Testing Virtual Accounts 

For Sandbox or Production access to Virtual Accounts, you will need to first [contact Sales](https://plaid.com/contact) or your Account Manager. Virtual Accounts are not supported in Limited Production.

#### Next steps 

To get started building with Virtual Accounts, see [Add Virtual Accounts to your App](https://plaid.com/docs/payment-initiation/virtual-accounts/add-to-app/index.html.md) .

---


# Payments (Europe) - Managing your Virtual Account | Plaid Docs

Managing your Virtual Account 
==============================

#### Set up, control, and monitor virtual account activity 

By default, you are able to create virtual accounts in Sandbox. Start by calling [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) . In order to use virtual accounts in Production, contact your Account Manager.

#### Accessing Virtual Account details 

To fetch virtual account details, use [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) or [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) .

#### Fund your Virtual Account 

You can top up your virtual account in two ways: a manual bank transfer or [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) . In Sandbox, virtual accounts must be funded using Payment Initiation.

To fund a virtual account via a manual bank transfer, initiate a transfer from your bank account by specifying the virtual account numbers as the transaction's recipient.

To fund a virtual account via Payment Initiation, follow the typical [Payment Initiation flow](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md) . Use the `recipient_id` associated with your `wallet_id` so Plaid knows to route the payment to your virtual account.

#### Webhooks 

An [overview of webhooks at Plaid](https://plaid.com/docs/api/webhooks/index.html.md) is available in the API Reference. There you can find general information on Plaid webhooks, including IP addresses, webhook verification, and retry logic.

To get status updates on all transaction activity in the virtual account, set up a webhook listener endpoint via the [Plaid Dashboard](https://dashboard.plaid.com/developers/webhooks) . Use the `Wallet transaction event` type with your webhook URL. Plaid will fire the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook to alert you when there are any changes to the status of a transaction.

#### Reconciling transactions 

To reconcile transactions:

1.  Call the [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) or [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) endpoint for the virtual account you want to pull transactions for.
    
2.  Cross-check the received transaction IDs with your stored transactions and compare the transaction statuses to ensure they are up to date. If the stored status is different, update it with the transaction status from the [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) or [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) endpoint in Step 1.
    

Plaid supports the [transaction types linked here](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet-transaction-get-response-type) .

Valid [transaction statuses](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet-transaction-get-response-status) for each transaction type are outlined below.

##### Credit transactions 

Credit transaction types: `PIS_PAY_IN` and `BANK_TRANSFER`

| Status      | Terminal   | Valid transitions   | Description |
| --- | --- | --- | --- |
| INITIATED | No | SETTLED, FAILED | The transaction has been initiated. |
| SETTLED | Yes |  | The transaction has settled in the virtual account. |
| FAILED | Yes |  | The transaction could not be executed, for example, due to an invalid recipient or invalid reference. |

##### Debit transactions 

Debit transactions types: `PAYOUT` and `REFUND`

| Status      | Terminal   | Valid transitions   | Description |
| --- | --- | --- | --- |
| AUTHORISING | No | INITIATED, FAILED, BLOCKED | The transaction is being processed for validation and compliance. |
| INITIATED | No | EXECUTED, FAILED | The transaction passed authorisation checks and is being processed by the payment network. |
| EXECUTED | Yes |  | The transaction has been successfully executed. Plaid does not have visibility into the settlement of debit transactions in the destination account. A transaction will typically settle within seconds to several days, depending on which payment rail is used. On rare occasions, a transaction may fail to settle after being executed, for example, if it is rejected by the payment rails due to compliance or anti-money-laundering checks. |
| FAILED | Yes |  | The transaction failed, for example, due to an invalid recipient or invalid reference. |
| BLOCKED | Yes |  | The transaction was blocked due to compliance checks and could not be executed. |

#### Idempotency 

An idempotency key is a unique value generated by you that allows Plaid to identify subsequent retries of the same request. A unique idempotency key should be generated for each different request. An idempotency key should be re-used only when retrying an existing request. You can choose how to create unique keys. We suggest using either V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 128 characters long.

Idempotency keys are valid for 24 hours after the first request. After 24 hours, any request reusing a previously-used idempotency key will be treated as a new request. When two requests with the same idempotency key, within 24 hours, have a different payload, the request will result in an error.

The `idempotency_key` is required for the [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) and [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) endpoints as it allows users to safely retry failed requests without creating a duplicate transaction. By providing the same `idempotency_key` for the same request, no more than one transaction is created.

---


# Payments (Europe) - Payment Confirmation | Plaid Docs

Payment Confirmation 
=====================

#### Confirm when funds have settled in a virtual account 

Plaid offers Payment Confirmation on top of our [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) APIs. Payment Confirmation provides confirmation of payments settling in your virtual account. Plaid will notify you when funds have settled so you can confidently release those funds to your end users. Each virtual account can receive or send funds on payment rails supported by the currency of the account.

The Payment Confirmation flow builds on the Payment Initiation flow, with two main differences:

*   Payments are initiated with the client-owned virtual account as the recipient.
    
*   Optionally, the current balance of the virtual account can be automatically swept (transferred) periodically to your bank account. To use this functionality, reach out to your Account Manager.
    

To your end user, there is no difference between initiating a payment to a virtual account and initiating a payment directly to the recipient bank account.

#### Confirming funds have settled 

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see [Managing virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md) .

1.  Go through the [Payment Initiation flow](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md) and initiate a payment.
    
    *   Use the `recipient_id` associated with your `wallet_id` so Plaid knows to route the payment to your virtual account.
2.  The payment will settle in your virtual account. You will receive the following webhooks:
    
    *   If you included a webhook URL when creating your `link_token` you will receive a [status update](https://plaid.com/api/products/payment-initiation/#payment_status_update) that the payment is now `SETTLED`. This is the primary webhook that indicates payment confirmation.
        
    *   If you configured a webhook through the [Plaid Dashboard](https://dashboard.plaid.com/developers/webhooks) , you will also receive a [status update](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) that a transaction of type `PIS_PAY_IN` transitioned from `INITIATED` to `SETTLED` in your virtual account. This webhook indicates an update to your virtual account with the funds that have settled (i.e., the transaction that corresponds to the payment that settled).
        
    *   Alternatively, if you are not using webhooks, you can check if the payment has settled by calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) with the `payment_id` from Step 1.
        
3.  Once the payment has settled, you can safely release funds to your end user.
    

In the UK, payments settle nearly instantly and run on the Faster Payment Services rails. In Europe, Plaid defaults to instant settlement times with SEPA Instant Credit rails when possible, and SEPA Credit Transfer otherwise.

#### Testing Payment Confirmation 

You can begin testing Payment Confirmation in Sandbox by following the steps listed in the [Add Virtual Accounts to your App](https://plaid.com/docs/payment-initiation/virtual-accounts/add-to-app/index.html.md) guide. For Production access you will first need to [submit a product access request Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

---


# Payments (Europe) - Payouts | Plaid Docs

Payouts 
========

#### Send funds from your virtual account 

A payout represents the flow of funds from a client’s virtual account to an end user. A payout can be for an arbitrary amount if you have sufficient funds stored in your virtual account to cover the payout. Using Payouts requires integrating with virtual account API routes and receiving transaction webhooks.

#### Execute a Payout 

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see [Managing virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md) .

1.  Call [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) to check your virtual account balance.
    
    *   If you have insufficient funds to make your desired payout, make sure to [fund your virtual account](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md#fund-your-virtual-account) before proceeding. After funding your virtual account, another request to [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) will show the updated balance.
2.  Call [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) and store the `transaction_id` and status from the response.
    
    *   If you have [configured transaction webhooks](https://dashboard.plaid.com/developers/webhooks) , you will receive real-time [status update webhooks](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) for each payout transaction.
        
    *   Alternatively, if not using webhooks, you can confirm the transaction has been executed by calling [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) with the `transaction_id`.
        

#### Testing Payouts 

You can begin testing Payouts in Sandbox by following the steps listed in the [Add Virtual Accounts to your App](https://plaid.com/docs/payment-initiation/virtual-accounts/add-to-app/index.html.md) guide. For Production access you will first need to [submit a product access request Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

---


# Payments (Europe) - Refunds | Plaid Docs

Refunds 
========

#### Refund a Payment Initiation payment 

Refunds enable you to refund your end users. You can issue refunds for any [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) payments that have settled in your virtual account.

*   The original payment must be in a settled state to be refunded.
    
*   To refund partially, specify the amount as part of the request.
    
*   If the amount is not specified, the refund amount will be equal to all of the remaining payment amount that has not been refunded yet.
    
*   If the remaining payment amount is less than one unit of currency (e.g. 1 GBP or 1 EUR), the refund will fail.
    

#### Execute a Refund 

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see [Managing virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md) .

1.  Follow the [Payment Confirmation](https://plaid.com/docs/virtual-accounts/payment-confirmation/index.html.md#confirming-funds-have-settled) flow to pay into your virtual account.
    
2.  Call [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) to check your virtual account balance for sufficient funds.
    
    *   If you have insufficient funds, [fund your virtual account](https://plaid.com/docs/payment-initiation/virtual-accounts/managing-virtual-accounts/index.html.md#fund-your-virtual-account) before proceeding. After funding your virtual account, you can check the updated balance by calling [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) .
3.  Issue a refund by calling [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) , providing the `payment_id` from the payment made in Step 3, and optionally an `amount` for partial refunds. Store the `refund_id` and `status` from the response.
    
    *   If you have [configured transaction webhooks](https://dashboard.plaid.com/developers/webhooks) , you will receive a status update that the Refund transitioned from `INITIATED` to `EXECUTED`.
        
    *   Alternatively, if not using webhooks, you can confirm the transaction has been executed by calling [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) with the `transaction_id`.
        
    *   You can also confirm that the original payment was refunded by calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) with the `payment_id` to see the `refund_id` as part of the payment’s details.
        
4.  If you have previously executed any partial refunds for the payment, you can still issue subsequent refunds if this payment has sufficient remaining amount.
    
    *   To check if the payment has sufficient remaining amount, call [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and fetch the `amount_refunded` field, which represents the amount that has been refunded already. Subtract this from the payment amount to calculate the amount still available to refund.

A successful refund will transition to the `EXECUTED` status. If a refund is in a `FAILED` status, you may try again, with a new `idempotency_key`, until you have a refund in an `EXECUTED` status for the payment. Refunds should transition to `EXECUTED` or `FAILED` automatically. If this does not occur,

#### Testing Refunds 

You can begin testing Refunds in Sandbox by following the steps listed in the [Add Virtual Accounts to your App](https://plaid.com/docs/payment-initiation/virtual-accounts/add-to-app/index.html.md) guide. For Production access you will first need to [submit a product access request Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

---


# Payments and Funding | Plaid Docs

Payment products 
=================

#### Review and compare payment and account funding solutions 

This page provides overviews of Plaid's payment and funding solutions to help you find the right one for your needs.

#### Auth 

[Auth](https://plaid.com/docs/auth/index.html.md) is a flexible solution for account and routing number verification that can be used with either a Plaid payments [processor partner](https://plaid.com/docs/auth/partnerships/index.html.md) , or any other processor of your choice, for payments processing.

#### Transfer 

[See a live, interactive demo](https://plaid.coastdemo.com/share/66faf2bfb0feffe54db38114?zoom=100) of a Plaid-powered payment flow using Transfer.

[Transfer](https://plaid.com/docs/transfer/index.html.md) is an end-to-end payment processing solution that performs funds transfers.

#### Auth and Transfer comparison 

Auth provides the most flexibility in terms of supported use cases and integration modes, while Transfer provides a single, end-to-end solution for funds transfers.

|  | Auth | Transfer |
| --- | --- | --- |
| Summary | An extensible account verification solution that plugs into your payments infrastructure | An out of the box, end-to-end solution for payments |
| Verifies account and routing numbers | Yes | Yes |
| Supports non-credential-based flows for account verification | Yes | Yes |
| Processes ACH transfers | No, requires a [processor partner or other processor](https://plaid.com/docs/auth/index.html.md#using-a-payments-service) | Yes |
| Provides optional out of the box UI for transfer authorization | No | Yes |
| Checks for ACH return risk | When used with Balance and/or Signal | Yes |
| Checks for account takeover risk | When used with Identity or Identity Match | When used with Identity or Identity Match |
| Supported countries | US, CA, UK, Europe | US |
| Supports peer-to-peer and marketplace payments | Yes | No |
| Supported use cases and industries | Wider range of supported use cases and industries | More restricted range of supported use cases and industries |
| Supported payment rails | Standard ACH, Same Day ACH, RTP, RfP, Wire, and international payment schemes | Standard ACH, Same Day ACH, RTP, RfP, Wire (for domestic credit transfers only) |
| Billing plans available | Pay-as-you-go or 12-month contract | 12-month contract (Custom only) |

#### Balance 

[Balance](https://plaid.com/docs/balance/index.html.md) gets real-time balances to reduce ACH risk and is typically used with Auth. A balance check engine is built in to Transfer, so Balance is only used with Transfer if using your own custom balance thresholds.

#### Signal 

[Signal](https://plaid.com/docs/signal/index.html.md) uses ML modeling to predict the risk of ACH returns with the lowest latency and can be used with either Auth or Transfer.

#### Balance and Signal comparison 

Balance is a simple and affordable solution for predicting closed account and insufficient funds returns (over 75% of returns). Signal is a premium, higher-priced solution that provides greater accuracy and much lower latency in assessing return risk to reduce abandon rates during critical flows in the user funnel, such as checkout and account funding. Signal is recommended for more sophisticated risk management teams willing to configure and tune score thresholds, high-risk use cases, or for asynchronous flows where avoiding user abandons during the risk check is critical.

|  | Balance | Signal |
| --- | --- | --- |
| Summary | Get real-time balance to minimize the risk of returns | Use ML modeling to quickly predict the risk of ACH returns |
| Advantages | Simple to use, low cost | Lowest latency, most accurate results, supports low-code integration as well as integrating with your existing risk engine |
| Can predict wide variety of ACH return codes | No, R01 and R02 only | Yes |
| Supported countries | US, CA, UK, Europe | US |
| Supported payment methods | Any: ACH, wires, RTP, etc. | ACH only |
| p50 latency | ~ 3 seconds | ~ 1 second |
| p95 latency | ~ 11 seconds | < 2 seconds |
| Billing plans available | Pay-as-you-go or 12-month contract | 12-month contract (Custom only) |

#### Identity 

[Identity](https://plaid.com/docs/identity/index.html.md) compares account info you hold about your customers to bank account ownership details to reduce account takeover risk. It is commonly used with Auth and Transfer, especially in high risk use cases.

#### Identity and Identity Match comparison 

[Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) is an optional add-on to [Identity](https://plaid.com/docs/identity/index.html.md) that provides greater ease of integration and data minimization. Customers using Identity Match can experience onboarding conversion improvements of 20% or more, without increasing fraud rates, when using Identity Match versus using their own matching algorithms.

|  | Identity | Identity Match |
| --- | --- | --- |
| Summary | Get account holder info on file with bank | Compare account holder info with info on file at bank |
| Avoids the need to build complex string matching logic | No | Yes |
| Minimizes PII stored in system | No | Yes |
| Integrates with [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) | No | Yes |
| Works with accounts verified via loginless flows such as [Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) or [Database Insights](https://plaid.com/docs/auth/coverage/database/index.html.md) | No | Supports ~30% of accounts verified by these flows |
| Supported countries | US, CA, UK, Europe | US, UK, Europe (CA: Early availability only, [contact sales](https://plaid.com/contact/) ) |
| Billing plans available | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract |

#### Investments Move 

[Investments Move](https://plaid.com/docs/investments-move/index.html.md) (US/CA only) is designed specifically for automating data entry and reducing user friction for brokerage-to-brokerage ACATS and ATON transfers, helping reduce abandon rates and failed transfers for new users moving their assets to your brokerage. Unlike other products on this page, it cannot be used to move money between bank accounts, only to move holdings from one brokerage to another.

#### Payments (Europe) 

Plaid's [Payments suite](https://plaid.com/docs/payment-initiation/index.html.md) enables your users to make real-time payments without manually entering their account number and sort code, or leaving your app.

#### Virtual Accounts (Europe) 

[Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) enables wallet-based features for your payments. Virtual Accounts can be used alongside other Payments components to enhance its capabilities with returns, settlement status visibility, and payouts, and can also be used on its own to add payout capabilities to apps that accept bank transfers from other sources.

#### Payment Initiation and Virtual Accounts comparison 

|  | Payments (without Virtual Accounts) | Virtual Accounts |
| --- | --- | --- |
| Summary | Enable end users to make real-time, in-app payments | Manage and track payments made by end users |
| Allows end-users to make payments via Link | Yes | No |
| Supports recurring payments | UK only, via [VRP](https://plaid.com/docs/payment-initiation/vrp/index.html.md) | UK only, via VRP, only if used with [Payments](https://plaid.com/docs/payment-initiation/vrp/index.html.md) |
| Supports issuing payouts | No | Yes |
| Supports issuing returns | No | Yes, only if used with Payments |
| Provides payment status updates | Yes | Yes, only if used with Payments |
| Indicates whether a payment has settled | No | Yes, only if used with Payments |
| Supported countries | [18 European countries](https://support.plaid.com/hc/en-us/articles/27895826947735-What-Plaid-products-are-supported-in-each-country-and-region) (including UK) | [18 European countries](https://support.plaid.com/hc/en-us/articles/27895826947735-What-Plaid-products-are-supported-in-each-country-and-region) (including UK) |
| Supports non-Eurozone local payments | Yes | Yes |
| Billing plans available | 12-month contract (Custom only) | 12-month contract (Custom only) |

---


# Protect - Introduction to Protect | Plaid Docs

Introduction to Protect  
=========================

#### Prevent fraud before it happens — at every step of the user lifecycle. 

Get started with Plaid Protect

[API Reference](https://plaid.com/docs/api/products/protect/index.html.md) [Request Access](https://plaid.com/products/protect/#contact-form)

#### Overview 

Plaid Protect defends you from financial fraud. Using Plaid's exclusive data and unique position in the financial ecosystem, Protect can detect patterns that identify fraud long before a transaction fails or an identity check triggers an alert. Protect is designed to detect all forms of fraud, ranging from isolated bad actors using stolen credit cards to sophisticated, scaled operations using automation, synthetic identities and insider knowledge.

At its core, Protect is two parts:

**The Trust Index**: A fraud model built on rich, network-wide data. The Trust Index delivers a dynamic score throughout the user journey, helping you apply the right friction at the right time while improving conversion.

**An investigative toolkit**: Protect offers a best-in-class toolkit designed specifically for fraud teams, allowing you to go from learning about a fraud ring to deploying mitigating rules in seconds.

The Protect API provides programmatic access to the Trust Index, allows you to send your own user events, and enables you to receive webhooks for asynchronous user updates.

To get started with Protect, [contact Sales](https://plaid.com/products/protect/#contact-form) to request access. Protect is currently available in the US only (financial account activity at institutions outside the US cannot be analyzed).

#### Dashboard 

Once enabled for Plaid Protect, you will be able to explore your customer traffic via the [Protect Dashboard](https://dashboard.plaid.com/protect) . You can search and filter events, save those searches as rules, and use those saved rules to configure your workflows.

#### Integration overview 

To access the Trust Index Score via API, update your existing integration as follows:

1.  In [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , add `protect_linked_bank` to the `products` or `required_if_supported_products` array. The end user will complete the Link flow as normal.
    
2.  After the Link session is finished, call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) with the Link token to retrieve the Trust Index Score computed for that Link session.
    

#### Optional integration features 

##### Sending Events 

While Plaid Protect tracks events within the Plaid ecosystem, you can also send events from your own application and retrieve an instant Trust Index score by calling [/protect/event/send](https://plaid.com/docs/api/products/protect/index.html.md#protecteventsend) .

##### User Insights 

To retrieve the latest Trust Index score for a user, call [/protect/user/insights/get](https://plaid.com/docs/api/products/protect/index.html.md#protectuserinsightsget) .

##### Webhooks 

To be alerted when Plaid Protect detects a user event (for example, name or account information on a user's bank account has changed), listen for the [PROTECT\_USER\_EVENT](https://plaid.com/docs/api/products/protect/index.html.md#protect_user_event) webhook.

If you would like a score from the event, you can then call [/protect/event/get](https://plaid.com/docs/api/products/protect/index.html.md#protecteventget) to retrieve full details along with the Trust Index score from that event.

---


# Quickstart - Glossary | Plaid Docs

Glossary 
=========

#### A glossary of Plaid terminology 

#### Tokens, identifiers, and keys 

Plaid tokens are in the format `[type]-[environment]-[uuid]`, where the type may be `public`, `access`, `link`, or `asset-report`, and the environment may be `sandbox`, `development`, or `production`; a token will only ever be valid within the environment it was created. The UUID is a 32 character hexadecimal string in the pattern of 8-4-4-4-12 characters and conforms to the [RFC 4122 standard](https://tools.ietf.org/html/rfc4122) .

##### Access token 

An `access_token` is a token that can be used to make API requests related to a specific Item. You will typically obtain an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . For more details, see the [Token exchange flow](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) . An `access_token` does not expire, although it may require updating, such as when a user changes their password, or if the end user is required to renew their consent on the Item. For more information, see [When to use update mode](https://plaid.com/docs/link/update-mode/index.html.md#when-to-use-update-mode) .

Access tokens should always be stored securely, and associated with the user whose data they represent. For more details on safely storing access tokens, see the [Open Finance Data Security Standard](https://ofdss.org/#documents) . An `access_token` can only be used to make a request if a Plaid API [client id](https://plaid.com/docs/quickstart/glossary/index.html.md#client-id) and [secret](https://plaid.com/docs/quickstart/glossary/index.html.md#secret) are also provided, and cannot be used on its own. If compromised, an `access_token` can be rotated via [/item/access\_token/invalidate](https://plaid.com/docs/api/items/index.html.md#itemaccess_tokeninvalidate) . If no longer needed, it can be revoked via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) .

##### Asset report token 

An `asset_report_token` is a token used to make API requests related to a specific Asset Report. You will obtain an `asset_report_token` by calling [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) . An `asset_report_token` does not expire, and should always be stored securely, and should be associated in your database with the user whose data it represents. If compromised or no longer needed, an `asset_report_token` can be revoked via [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) .

##### Client ID 

Your `client_id` is an identifier required by the Plaid API. It must be provided for almost all API calls. Your client ID can be found on the [Dashboard](https://dashboard.plaid.com/developers/keys) . Your client ID uniquely identifies your team and will be the same for all API calls made on behalf of your organization, regardless of the API environment or the specific individual using the API.

##### Item ID 

An `item_id` uniquely identifies a Plaid [Item](https://plaid.com/docs/quickstart/glossary/index.html.md#item) . The `item_id` is part of the response for API endpoints that operate on a specific Item, including most product endpoints, as well as [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) and [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .

##### Link token 

A `link_token` is a token used to initialize Link, and must be provided any time you are presenting your user with the Link interface. You can obtain a Link token by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . For more details, see the the [Token exchange flow](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) . A `link_token` expires after 4 hours (or after 30 minutes, when being used with update mode), except when using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) , which allows customizing the `link_token` lifetime, or when used with Identity Verification, in which case it does not expire.

##### Link session ID 

The `link_session_id` is a unique ID included in all Link callbacks. For faster issue resolution, the `link_session_id` should be included when contacting Support regarding a specific Link session.

##### Processor token 

A `processor_token` is a token used by a Plaid partner to make API calls on your behalf. You can obtain a `processor_token` by calling [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) and providing an `access_token`. The `processor_token` does not expire. Once successfully passed to the processor, it can be either deleted from your database, or retained to manage the processor's permissions and access via [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) . You should always retain the `access_token`, since it will be needed to activate [update mode](https://plaid.com/docs/link/update-mode/index.html.md) for the underlying Item.

##### Public token 

A `public_token` is a token obtained after Link, typically from the `onSuccess` callback. This token can be exchanged for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . For more details, see the [Token exchange flow](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) . A `public_token` expires after 30 minutes. If using the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) flow or [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) flow, the public token is instead obtained from the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint, the `SESSION_FINISHED` webhook, or the `ITEM_ADD_RESULT` webhook.

##### Request ID 

A `request_id` is a unique ID returned as part of the response body for every Plaid API response (except for API endpoints that return binary data, in which case the `request_id` will be found in the header). The `request_id` can be used to look up the request on the [Activity Log](https://dashboard.plaid.com/activity/logs) and should be included when contacting Support regarding a specific API call.

##### Secret 

Your secret is used to authenticate calls to the Plaid API. Secrets can be found on the [dashboard](https://dashboard.plaid.com/developers/keys) . Your secret should be kept secret and rotated if it is ever compromised. For more information, see [rotating keys](https://plaid.com/docs/account/security/index.html.md#rotating-keys) .

##### User token 

A `user_token` is used when working with Plaid's Income or Employment APIs, with Plaid Check, or with the Multi-Item Link flow. It is used to associate data from multiple sources with a single user and must be provided when initializing [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for these flows. A `user_token` is created by calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and does not expire. Ensure that you store the `user_token` along with your user's identifier in your database, as it is not possible to retrieve a previously created `user_token`.

#### Environments 

To use Link with bank data in Production or Limited Production in the US or Canada, all customers who created accounts after October 31, 2024 must [select a use case description](https://dashboard.plaid.com/link/data-transparency-v5) from the Link Customization section of the Dashboard.

##### Production 

Production ([https://production.plaid.com](https://production.plaid.com) ) is one of two Plaid environments on which you can run your code, along with Sandbox. Unlike Sandbox, Production uses real data.

##### Limited Production 

Limited Production is a restricted mode of the Production ([https://production.plaid.com](https://production.plaid.com) ) environment. In Limited Production, you can make free API calls using real-world data for testing purposes, but the number of API calls you can make and the number of Items you can create is capped, and you cannot connect to certain large institutions that use OAuth, like Bank of America, Chase, or Wells Fargo. To remove these limitations, apply for full Production access and complete the OAuth registration form. You will still be able to use your remaining free API calls in full Production before being billed. For more details on Limited Production, see [Testing with live data using Limited Production](https://plaid.com/docs/sandbox/index.html.md#testing-with-live-data-using-limited-production) .

The following products are supported in Limited Production: Assets, Auth, Balance, Identity (including Identity Match), Income, Investments, Liabilities, Payment Initiation, Transactions (including Transactions Refresh and Recurring Transactions), and Enrich.

##### Sandbox 

The Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ) is one of two Plaid environments on which you can run your code, along with Production. Sandbox is a free test environment in which no real data can be used. The Sandbox environment also offers a number of special Sandbox-only capabilities to make testing easier. For more information, see [Sandbox](https://plaid.com/docs/sandbox/index.html.md) .

##### Development 

Development ([https://development.plaid.com](https://development.plaid.com) ) was a Plaid environment on which you could run your code, along with Sandbox and Production. To simplify the development process, Plaid replaced the Development environment with the ability to test with real data for free directly in Production. On June 20, 2024, the Plaid Development environment was decommissioned, and all Development Items were removed.

#### Other Plaid terminology 

##### Account 

An account is a single account held by a user at a financial institution; for example, a specific checking account or savings account. A user may have more than one account at a given institution; the overall object that contains all of these accounts is the Item. Each account is uniquely identified by an `account_id`, which will not change, unless Plaid is unable to reconcile the account with the data returned by the financial institution; for more information, see [INVALID\_ACCOUNT\_ID](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_account_id) .

Plaid will automatically detect when an account is closed, and will no longer return the `account_id` for a closed account. If an `access_token` is deleted, and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date, the new `account_id` will be different from the `account_id` associated with the original `access_token`.

##### Dashboard 

The Plaid Dashboard is used to manage your Plaid developer account, configure your account for OAuth, and to obtain keys and secrets. The Dashboard also contains a number of useful features, including troubleshooting tools, activity and usage logs, billing data, details and status for supported institutions, and the ability to request additional products or environments or to submit a support ticket. It can be found at [dashboard.plaid.com](https://dashboard.plaid.com) . For more information, see [Your Plaid developer account](https://plaid.com/docs/account/index.html.md) .

##### Item 

An Item represents a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. Each Item linked within your application will have a corresponding `access_token`, which is a token that you can use to make API requests related to that specific Item.

Two Items created for the same set of credentials at the same institution will be considered different and not share the same `item_id`.

##### Link 

Link is Plaid's client-side, user-facing UI that allows end users to connect their financial institution account to your application. For more information, see [Link](https://plaid.com/docs/link/index.html.md) .

##### Plaid Consumer Reporting Agency 

Plaid Consumer Reporting Agency, also known as Plaid CRA or Plaid Check, is focused on building solutions for customers who want ready-made credit risk insights from consumer-permissioned cash flow data. Plaid Check is a Consumer Reporting Agency as defined by the Fair Credit Reporting Act (FCRA), allowing it to provide enhanced insights not available from Plaid Inc. products. For more information, see [Plaid Check](https://plaid.com/docs/check/index.html.md) . Plaid's other products described in the docs, including Assets, Statements, and Income, are provided by Plaid Inc., which is not a consumer reporting agency.

---


# Quickstart | Plaid Docs

Get started with the Quickstart 
================================

#### A quick introduction to building with Plaid 

[Watch video](https://www.youtube.com/watch?v=U9xa1gzyPx8)

Want more video tutorials? The [full getting started guide](https://www.youtube.com/watch?v=sGBvKDGgPjc) for the Quickstart app is available on YouTube.

Don't want to write code? Check out the [Plaid Postman Collection](https://github.com/plaid/plaid-postman) for a no-code way to get started with Plaid's API.

Looking to get started with Identity Verification or Income Verification? For Identity Verification, check out the [Identity Verification Quickstart](https://github.com/plaid/idv-quickstart) . For Income, try the [Income Verification Starter app](https://github.com/plaid/income-sample) .

### Introduction 

Let’s test out running Plaid locally by cloning the Quickstart app. You’ll need API keys, which you can receive by signing up in the [Dashboard](https://dashboard.plaid.com/developers/keys) .

You'll have two different API keys, and there are three different Plaid environments. Today we'll start in the Sandbox environment. View the API Keys section of the Dashboard to find your Sandbox secret.

###### API Key 

[View Keys in Dashboard](https://dashboard.plaid.com/developers/keys)

client\_id

Private identifier for your team

secret

Private key, one for each of the three environments

###### Environment 

Sandbox

Get started with test credentials and life-like data

Production

Test or launch your app with unlimited live credentials

If you get stuck at any point in the Quickstart, help is just a click away! Check the Quickstart [troubleshooting guide](https://github.com/plaid/quickstart#troubleshooting) or ask other developers in our [Stack Overflow community](https://stackoverflow.com/questions/tagged/plaid) .

### Quickstart setup 

Once you have your API keys, it's time to run the Plaid Quickstart locally! The instructions below will guide you through the process of cloning the [Quickstart repository](https://github.com/plaid/quickstart) , customizing the .env file with your own Plaid client ID and Sandbox secret, and finally, building and running the app.

Plaid offers both Docker and non-Docker options for the Quickstart. If you don't have Docker installed, you may wish to use the non-Docker version; this path is especially recommended for Windows users who do not have Docker installations. However, if you already have Docker installed, we recommend the Docker option because it is simpler and easier to run the Quickstart. Below are instructions on setting up the Quickstart with Docker and non-Docker configurations.

Select group for content switcher

Non-DockerDocker

#### Setting up without Docker 

Make sure you have [npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) before following along. If you're using Windows, ensure you have a terminal capable of running basic Unix shell commands.

```bash
# Note: If on Windows, run
# git clone -c core.symlinks=true https://github.com/plaid/quickstart
# instead to ensure correct symlink behavior


git clone https://github.com/plaid/quickstart.git


# Copy the .env.example file to .env, then fill
# out PLAID_CLIENT_ID and PLAID_SECRET in .env
cp .env.example .env


cd quickstart/node


# Install dependencies
npm install


# Start the backend app
./start.sh
```

Open a new shell and start the frontend app. Your app will be running at `http://localhost:3000`.

```bash
# Install dependencies
cd quickstart/frontend
npm install


# Start the frontend app
npm start


# Go to http://localhost:3000
```

Visit localhost and log in with Sandbox credentials (typically `user_good` and `pass_good`, as indicated at the bottom of the page).

(An image of "Plaid Quickstart guide with 'Launch Link' button to simulate user bank account integration.")

#### Setting up with Docker 

Docker is a software platform that packages software into standardized units called containers that have everything the software needs to run, including libraries, system tools, code, and runtime. If you don't already have Docker, you can [download it from the Docker site](https://docs.docker.com/get-docker/) . Note that Windows users may need to take some additional steps, such installing a Linux environment; if you are using Windows and do not already have a Linux environment installed, we recommend selecting the non-Docker instructions instead.

Once Docker is installed, launch the Docker app, then use the following commands at the command line to configure and run the Quickstart. If the `make` commands do not work, ensure that Docker is running. You may also need to prefix the `make` commands with `sudo`, depending on your environment.

```bash
# Note: If on Windows, run
# git clone -c core.symlinks=true https://github.com/plaid/quickstart
# instead to ensure correct symlink behavior


git clone https://github.com/plaid/quickstart.git
cd quickstart


# Copy the .env.example file to .env, then fill
# out PLAID_CLIENT_ID and PLAID_SECRET in .env
cp .env.example .env


# start the container for one of these languages:
# node, python, java, ruby, or go


make up language=node


# Go to http://localhost:3000
```

Visit localhost and log in with Sandbox credentials (typically `user_good` and `pass_good`, as indicated at the bottom of the page).

(An image of "Plaid Quickstart page with 'Launch Link' button to connect bank accounts via Plaid API integration.")

```bash
$ make logs language=node
```

```bash
$ make stop language=node
```

#### Create your first Item 

Most API requests interact with an _Item_, which is a Plaid term for a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.

Now that you have the Quickstart running, you’ll add your first Item in the Sandbox environment. Once you’ve opened the Quickstart app on localhost, click the **Launch Link** button and select any institution. Use the Sandbox credentials to simulate a successful login.

##### Sandbox credentials 

```bash
username: user_good
password: pass_good
If prompted to enter a 2FA code: 1234
```

Once you have entered your credentials and moved to the next screen, you have created your first Item! You can now make API calls for that Item by using the buttons in the Quickstart. In the next section, we'll explain what actually happened and how the Quickstart works.

### How it works 

As you might have noticed, you use both a server and a client-side component to access the Plaid APIs. The flow looks like this:

**The Plaid flow** begins when your user wants to connect their bank account to your app.

(An image of "Step diagram")

**1**Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to create a `link_token` and pass the temporary token to your app's client.

(An image of "Step 1 diagram")

**2**Use the `link_token` to open Link for your user. In the [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) , Link will provide a temporary `public_token`. This token can also be obtained on the backend via \`/link/token/get\`.

(An image of "Step 2 diagram")

**3**Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for a permanent `access_token` and `item_id` for the new `Item`.

(An image of "Step 3 diagram")

**4**Store the `access_token` and use it to make product requests for your user's `Item`.

(An image of "Step 4 diagram")

The first step is to create a new `link_token` by making a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request and passing in the required configurations. This `link_token` is a short lived, one-time use token that authenticates your app with [Plaid Link](https://plaid.com/docs/link/index.html.md) , our frontend module. Several of the environment variables you configured when launching the Quickstart, such as `PLAID_PRODUCTS`, are used as parameters for the `link_token`.

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

Once you have a `link_token`, you can use it to initialize [Link](https://plaid.com/docs/link/index.html.md) . Link is a drop-in client-side module available for web, iOS, and Android that handles the authentication process. The Quickstart uses Plaid's optional React bindings for an integration that you trigger via your own client-side code. This is what your users use to log into their financial institution accounts.

After a user submits their credentials within Link, Link provides you with a `public_token` via the `onSuccess` callback. The code below shows how the Quickstart passes the `public_token` from client-side code to the server. Both React and vanilla JavaScript examples are shown.

```tsx
// APP COMPONENT
// Upon rendering of App component, make a request to create and
// obtain a link token to be used in the Link component
import React, { useEffect, useState } from 'react';
import { usePlaidLink } from 'react-plaid-link';
const App = () => {
  const [linkToken, setLinkToken] = useState(null);
  const generateToken = async () => {
    const response = await fetch('/api/create_link_token', {
      method: 'POST',
    });
    const data = await response.json();
    setLinkToken(data.link_token);
  };
  useEffect(() => {
    generateToken();
  }, []);
  return linkToken != null ?  : <>;
};
// LINK COMPONENT
// Use Plaid Link and pass link token and onSuccess function
// in configuration to initialize Plaid Link
interface LinkProps {
  linkToken: string | null;
}
const Link: React.FC = (props: LinkProps) => {
  const onSuccess = React.useCallback((public_token, metadata) => {
    // send public_token to server
    const response = fetch('/api/set_access_token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ public_token }),
    });
    // Handle response ...
  }, []);
  const config: Parameters[0] = {
    token: props.linkToken!,
    onSuccess,
  };
  const { open, ready } = usePlaidLink(config);
  return (
     open()} disabled={!ready}>
      Link account
    
  );
};
export default App;
```

Next, on the server side, the Quickstart calls [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to obtain an `access_token`, as illustrated in the code excerpt below. The `access_token` uniquely identifies an Item and is a required argument for most Plaid API endpoints. In your own code, you'll need to securely store your `access_token` in order to make API requests for that Item.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Making API requests 

Now that we've gone over the Link flow and token exchange process, we can explore what happens when you press a button in the Quickstart to make an API call. As an example, we'll look at the Quickstart's call to [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) , which retrieves basic information, such as name and balance, about the accounts associated with an Item. The call is fairly straightforward and uses the `access_token` as a single argument to the Plaid client object.

```javascript
app.get('/api/accounts', async function (request, response, next) {
  try {
    const accountsResponse = await client.accountsGet({
      access_token: accessToken,
    });
    prettyPrintResponse(accountsResponse);
    response.json(accountsResponse.data);
  } catch (error) {
    prettyPrintResponse(error);
    return response.json(formatError(error.response));
  }
});
```

Example response data:

```json
{
  "accounts": [
    {
      "account_id": "A3wenK5EQRfKlnxlBbVXtPw9gyazDWu1EdaZD",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "GPnpQdbD35uKdxndAwmbt6aRXryj4AC1yQqmd",
      "balances": {
        "available": 200,
        "current": 210,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "1111",
      "name": "Plaid Saving",
      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
      "subtype": "savings",
      "type": "depository"
    },
    {
      "account_id": "nVRK5AmnpzFGv6LvpEoRivjk9p7N16F6wnZrX",
      "balances": {
        "available": null,
        "current": 1000,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "2222",
      "name": "Plaid CD",
      "official_name": "Plaid Bronze Standard 0.2% Interest CD",
      "subtype": "cd",
      "type": "depository"
    }
    ...
  ],
  "item": {
    "available_products": [
      "assets",
      "balance",
      "identity",
      "investments",
      "transactions"
    ],
    "billed_products": ["auth"],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_12",
    "item_id": "gVM8b7wWA5FEVkjVom3ri7oRXGG4mPIgNNrBy",
    "webhook": "https://requestb.in"
  },
  "request_id": "C3IZlexgvNTSukt"
}
```

#### Next steps 

Congratulations, you have completed the Plaid Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Plaid API. There are a few directions you can go in now:

Go to the [docs homepage](https://plaid.com/docs/index.html.md) for links to product-specific documentation.

For more sample apps, including a bare-bones minimal Plaid Quickstart implementation and apps demonstrating real world examples of funds transfer and personal financial management, see [sample apps](https://plaid.com/docs/resources/index.html.md#sample-apps) .

Our YouTube playlist [Plaid in 3 minutes](https://www.youtube.com/playlist?list=PLyKH4ZiEQ1bE7XBcpX81BQWLy1olem1wf) has brief introductions to many Plaid products. For more detailed tutorial videos, see [Plaid Academy](https://www.youtube.com/playlist?list=PLyKH4ZiEQ1bH5wpCt9SiyVfHlV2HecFBq) .

Looking to move money with a Plaid partner, such as [Dwolla](https://plaid.com/docs/auth/partnerships/dwolla/index.html.md) ? See [Move money with our partners](https://plaid.com/docs/auth/partnerships/index.html.md) for partner-specific money movement Quickstarts.

The Quickstart covers working with web apps. If your Plaid app will be on mobile, see [Plaid Link](https://plaid.com/docs/link/index.html.md) to learn about getting started with mobile client-side setup.

Need help?

If you'd like to integrate with Plaid and don't have in-house technical resources, [contact a Plaid integration partner](https://plaid.com/docs/resources/index.html.md#integration-support) to build a Plaid integration for you.

---


# Resources | Plaid Docs

Plaid resources 
================

#### External resources to help build your Plaid integration 

In addition to the docs here, Plaid has a collection of tools, sample code, SDKs, and videos to help you build your Plaid integration.

#### Sample apps 

Our [GitHub](https://github.com/plaid) contains a number of sample apps to help you get started using Plaid!

**Quickstart**

Official Plaid Quickstart, using React, available in NodeJS, Python, Ruby, Java, and Go

**Tiny Quickstart**

A Plaid implementation in 150 lines. Available in JavaScript, Next.Js, React, and React Native frontends.

**Personal Finances**

Usages of Transactions, Assets, and Liabilities APIs, using NodeJS and React

**Personal Finances - Hosted**

A fully hosted, live version of the Personal Finances sample app

**Account Funding**

Auth, Identity, and Balance APIs for money movement, in NodeJS and React

**Account Funding in Europe**

Account funding using the Payment Initiation API, using NodeJS and React

**Transfer Quickstart**

Use Transfer to receive funds from customers, using NodeJS and JavaScript

**Identity Verification Quickstart**

See Plaid Identity Verification in action! (NodeJS only)

**Income**

A lending app using the Income API, using NodeJS and React

#### Demos, tutorials and guides 

##### Demos 

[demo.plaid.com](https://demo.plaid.com) features interactive demos showing API calls alongside the end user experience for many Plaid products and use cases, including account funding and verification, personal financial management with Transactions, credit and underwriting, pay-by-bank, and more.

##### Video tutorials 

[Plaid Academy](https://www.youtube.com/playlist?list=PLyKH4ZiEQ1bH5wpCt9SiyVfHlV2HecFBq) features detailed tutorial walkthroughs for common use cases and key concepts.

[Plaid in 3 Minutes](https://www.youtube.com/playlist?list=PLyKH4ZiEQ1bE7XBcpX81BQWLy1olem1wf) contains overviews of different Plaid APIs, as well as short tutorials for busy people.

[Plaid Quick tips](https://www.youtube.com/playlist?list=PLyKH4ZiEQ1bEAnnIiFMRGat7tFQl3gcJv) has snack-sized solutions to pressing Plaid problems.

The playlist below contains all of Plaid's up-to-date educational videos.

##### Integration guides 

Plaid offers several PDF guides with information from the docs provided in a step-by-step walkthrough format.

*   [Plaid implementation handbook](https://plaid.com/documents/plaid-implementation-handbook.pdf)
*   [Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf)
*   [Income verification integration guide](https://plaid.com/documents/plaid-income-verification-solution-guide.pdf)
*   [Assets solution guide](https://plaid.com/documents/plaid-assets-solution-guide.pdf)
*   [Account funding integration guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for Auth, Balance, and Identity use cases

##### Launch center 

The [Launch Center](https://dashboard.plaid.com/developers/launch-center) provides a list of steps to help make sure your app is Plaid-optimized and production ready.

#### Developer tools 

Developer tools include our SDKs, Postman collection, and OpenAPI file.

##### SDKs 

For information about official and community supported libraries for both the Plaid API and the Link frontend component, see [libraries](https://plaid.com/docs/api/libraries/index.html.md) .

##### Postman 

The [Postman Collection](https://github.com/plaid/plaid-postman) provides an easy, no-code way to explore the API.

##### OpenAPI file 

The [Plaid OpenAPI file](https://github.com/plaid/plaid-openapi) is available on GitHub. This file describes the Plaid API in a standardized way suitable for usage with tools for testing, client library generation, and other purposes that ingest OpenAPI/Swagger definition files.

##### Test data libraries 

Plaid maintains a repo of [configuration objects](https://github.com/plaid/sandbox-custom-users) suitable for usage as [custom Sandbox users](https://plaid.com/docs/sandbox/user-custom/index.html.md) to help you test apps in Sandbox.

##### Enrich test transaction library 

For testing Enrich, Plaid provides a list of [Sandbox-compatible Enrich transactions](https://plaid.com/documents/enrich_sandbox_preset_transactions.csv) .

##### Credit attributes library 

For the Assets and Income products, Plaid maintains a [Credit attributes library](https://github.com/plaid/credit-attributes) of helper scripts that can be used to derive various useful attributes from an Asset Report or Bank Income.

#### AI Developer Toolkit 

Plaid's AI toolkit includes a number of tools to help you incorporate AI tooling into your development flow.

##### Vibe coding tips 

Our [vibe coding tips](https://plaid.com/docs/resources/vibe-coding/index.html.md) article contains recommendations on how to get your favorite AI coding assistant or IDE to work best with Plaid, including common mistakes AI tools will make and how to fix them.

##### Dashboard MCP Server 

Plaid's [Dashboard MCP server](https://plaid.com/docs/resources/mcp/index.html.md) allows you to access Plaid's diagnostics and analytics tools to retrieve information about Link analytics, Item health, and more, using your favorite LLM-powered application or client library.

##### LLM-friendly documentation 

In accordance with the [llms-txt](https://llmstxt.org/) proposal, an index of all of Plaid's documentation can be found in LLM-friendly Markdown at [https://plaid.com/llms.txt](https://plaid.com/llms.txt) . You can find a Markdown equivalent of nearly all Plaid documentation pages by adding `index.html.md` to the end of the URL. For example, a Markdown version of [https://plaid.com/docs/auth](https://plaid.com/docs/auth/index.html.md) can be found at [https://plaid.com/docs/auth/index.html.md](https://plaid.com/docs/auth/index.html.md.md) .

Consult the documentation for your favorite LLM-powered coding assistant for the best way to incorporate this documentation into your workflow, as best practices are changing frequently. Often, adding a prompt like the following in your helper file can be useful.

```undefined
## Instructions on using the Plaid API


For instructions on how to use the Plaid API, please go to 
https://plaid.com/docs/llms.txt. There you can find a list of other
documentation pages that you can retrieve to obtain the necessary 
information. If you need to search for additional documentation, you
should first try to use a link that is listed in the llms.txt file.
```

A single file containing all of Plaid's documentation can be found at [https://plaid.com/docs/llms-full.txt](https://plaid.com/docs/llms-full.txt/index.html.md) , although it is generally too large to fit into most models' context windows.

##### "Vibe Coding" guides 

Trying to prompt your favorite LLM-powered coding tool to build a Plaid-powered application? Plaid provides several [detailed guides](https://github.com/plaid/ai-coding-toolkit/tree/main/rules) you can reference within your LLM coding session that will provide your agent with additional context. You can use these guides to more quickly build proof of concept applications, or to kick-start your development process.

##### Sandbox MCP server 

Plaid also provides a [Sandbox MCP server](https://github.com/plaid/ai-coding-toolkit/tree/main/sandbox) , which, when run locally, provides helpful utilities for building and testing your Plaid-powered applications. You can use the Sandbox MCP server to generate realistic looking [custom user data](https://plaid.com/docs/sandbox/user-custom/index.html.md) , simulate webhooks, or create public tokens in the [Sandbox environment](https://plaid.com/docs/sandbox/index.html.md) .

##### Ask Bill 

[Bill](https://plaid.com/docs/support/?showChat=true/index.html.md) is our helpful robot platypus that reads our docs for fun! You can [ask Bill](https://plaid.com/docs/support/?showChat=true/index.html.md) any time you need help with the Plaid API. Remember that Bill (like all of us) isn't perfect, even though he tries his best -- he can sometimes make mistakes, and he can only provide answers based on Plaid's published documentation and other publicly available information sources.

#### Community 

You can join the [Plaid Developer Community on Discord](https://discord.gg/sf57M8DW3y) or ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/plaid?tab=Newest) .

#### Integration support 

For small businesses and startups, [HumbleDevs](https://www.humbledevs.com/) is a popular Plaid integration partner offering affordable integration solutions. HumbleDevs offers several [pre-specced Plaid solutions packages](https://v1.humbledevs.com/solutions) with known timelines and costs for popular Plaid-powered solutions, and can also build a custom Plaid integration.

For larger businesses or those with other requirements, Plaid's partnerships team will work with you to understand your needs and recommend a partner that is a good fit for your business. For more information, contact your account manager or the [sales team](https://plaid.com/contact/) . Or, if you already have production access, you can [contact Support](https://dashboard.plaid.com/support/new/product-and-development/developer-lifecycle/developer-resources) and selecting "Building with Plaid" followed by "Plaid Partner Implementation Assistance".

At the enterprise level, Plaid also offers integration packages. For more details, [contact Sales](https://plaid.com/contact/) or your account manager.

#### Partner directory 

For more information about Plaid partners, see the [Partner directory](https://plaid.com/partner-directory/) .

The Partner directory is not a comprehensive list of all Plaid partners; if you don't see the partnership you're looking for, contact your Account Manager or the [sales team](https://plaid.com/contact/) .

#### Security portal, audits, and certifications 

For a high-level overview of information on Plaid's privacy and security practices for developers, see [Plaid Safety](https://plaid.com/safety/) .

For details on Plaid's current certifications, audit results, and the security knowledge base, see the [Security Portal](https://security.plaid.com/) .

Plaid maintains a [HackerOne bug bounty program](https://hackerone.com/plaid) for security researchers.

#### Third-party resources 

Several third party developers have built resources to help you integrate with Plaid. Note that these resources are not built or supported by Plaid, and inclusion of a resource on the list below does not constitute an endorsement by Plaid or indicate that Plaid has evaluated the resource for correctness, security, or anything else.

If you have a third-party resource you'd like to be featured on this list, DM us [@plaiddev](https://twitter.com/plaiddev) on X, or reach out to an admin on the [Plaid Developer Discord](https://discord.gg/sf57M8DW3y) .

*   [How to Build a Fintech app on AWS using the Plaid API](https://aws.amazon.com/blogs/apn/how-to-build-a-fintech-app-on-aws-using-the-plaid-api/) and the accompanying [sample app](https://github.com/aws-samples/aws-plaid-demo-app) demonstrates how to build a Plaid app on AWS, using the latest Transactions Sync API. The app and tutorial incorporate AWS Lambda for webhook handling and Amazon Cognito for authentication.
*   The [Plaid tag on GitHub](https://github.com/topics/plaid) contains multiple example apps using Plaid.
*   [CodeSandbox](https://codesandbox.io/examples/package/plaid) has several sample apps that use Plaid.
*   [WebhookDB](https://plaid.comhttps://webhookdb.com/docs/plaid/index.html.md) has a tutorial showing how to use their service to manage Plaid webhooks.
*   The [CloudQuery Plaid plugin](https://github.com/cloudquery/cq-source-plaid) extracts data from Plaid and loads it into any supported CloudQuery destination, such as PostgreSQL, Snowflake, BigQuery, or S3.

#### European Bank Coverage Explorer 

The European Bank Coverage Explorer has been moved [here](https://plaid.com/docs/institutions/europe/index.html.md) .

---


# Resources - MCP Server | Plaid Docs

Dashboard MCP Server 
=====================

#### Connect your LLM-powered application to Plaid’s developer tools 

For AI tools and applications, Plaid hosts a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that provides several tools to help you better understand your Plaid integration health, investigate user-facing issues, and more.

This article is intended for developers looking to build their own applications that can interact with the MCP server.

To use the MCP server with Claude Desktop, Cursor, VS Code, or Zed, see the [AI toolkit GitHub repo documentation](https://github.com/plaid/ai-coding-toolkit/tree/main/sandbox) instead.

For use with Claude.ai, documentation can be found on [Anthropic's website](https://support.anthropic.com/en/articles/10168395-setting-up-integrations-on-claude-ai) .

The Dashboard MCP server is a new feature under active development and breaking changes may occur. Plaid currently offers limited official support.

#### Integration Process 

##### Requirements 

The Dashboard MCP server only works with production data. You must be approved for production access with at least one Plaid product in order to use the MCP server.

##### Authorization 

In order to connect to the Dashboard MCP server, you must first create an OAuth token with the scope `mcp:dashboard` and the `client_credentials` grant type via the [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) API.

```bash
curl -X POST https://production.plaid.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "client_secret": "YOUR_PRODUCTION_SECRET",
    "grant_type": "client_credentials", 
    "scope": "mcp:dashboard"
  }'
```

This will return an `access_token` you can use to authenticate into the Dashboard MCP server. This will also return a `refresh_token` that you can use to request a new access token when the old one expires.

##### Creating the MCP connection 

Plaid's Dashboard MCP server is available at [https://api.dashboard.plaid.com/mcp/sse](https://api.dashboard.plaid.com/mcp/sse) , using the SSE Transport protocol. When you communicate with the MCP server, you must pass the `access_token` from the authorization step above via an `Authentication: Bearer <access_token>` header.

The exact method for connecting with the MCP server depends on the LLM client library you are using, but it is typically provided to the model as an entry in the list of tools that it can access. For more information, please refer to the documentation from your model provider, such as [OpenAI](https://plaid.comhttps://platform.openai.com/docs/guides/tools-remote-mcp/index.html.md) or [Anthropic](https://plaid.comhttps://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector/index.html.md) . Plaid recommends using the most recent version of your model's client library.

The following is a basic example of how to access the Dashboard MCP server using OpenAI or Anthropic's client libraries for Python.

Select group for content switcher

OpenAIAnthropic

```python
import json
import openai


def request_or_refresh_access_token():
    # For simplicity, we're just creating a new access token every time
    plaid_client = get_plaid_client()
    oauth_token_request = {
        "grant_type": "client_credentials",
        "scope": "mcp:dashboard",
    }


    response = plaid_client.oauth_token(oauth_token_request)
    return response["access_token"]




def main() -> None:
    """Run the example call and print the structured response."""


    client = openai.OpenAI()
    dashboard_token = request_or_refresh_access_token()


    response = client.responses.create(
        model="gpt-4.1",
        tools=[
            {
                "type": "mcp",
                "server_label": "plaid",
                "server_url": "https://api.dashboard.plaid.com/mcp/sse",
                "require_approval": "never",
                "headers": {"Authorization": "Bearer " + dashboard_token},
            }
        ],
        # input="What is the status of Item ID ?",
        input="Please examine all Link sessions over the last week and provide me with a detailed report. Call out any patterns you see among Link sessions that were not successful.",
    )


    # Nearly all calls to the openAI client will return the mcp_list_tools object
    # and an assistant message. If the client made a call to the MCP server,
    # it will also return one or more mcp_call objects.
    for item in response.output:
        if item.type == "mcp_list_tools":
            print("\n=== MCP Tools ===")
            for tool in item.tools:
                print(f" • {tool['name']}")


        elif item.type == "mcp_call":
            print("\n=== MCP Call ===")
            print(f"Tool: {item.name}")
            try:
                # The arguments field is a JSON string – parse it for readability.
                args = json.loads(item.arguments)
            except (TypeError, json.JSONDecodeError):
                args = item.arguments
            print("Arguments:")
            print(json.dumps(args, indent=2))


        elif item.type == "message":
            print("\n=== Assistant Message ===")
            # The content field is a list of ResponseOutputText objects.
            texts = []
            for part in item.content:
                # Depending on SDK version, `text` may be an attribute or dict key.
                text = getattr(part, "text", None) or (
                    part.get("text") if isinstance(part, dict) else None
                )
                if text:
                    texts.append(text)
            print("\n".join(texts))


        else:
            print(f"\n=== Unhandled output type: {item.type} ===")
            print(item)




if __name__ == "__main__":
    main()
```

```undefined
=== MCP Tools ===
 • plaid_debug_item
 • plaid_get_link_analytics
 • plaid_get_tools_introduction
 • plaid_get_usages
 • plaid_list_teams


=== MCP Call ===
Tool: plaid_list_teams
Arguments:
{}


=== MCP Call ===
Tool: plaid_get_link_analytics
Arguments:
{
  "from_date": "2025-05-01",
  "team_id": "58b9a231bdc6a453f37c338e",
  "to_date": "2025-05-08"
}


=== Assistant Message ===
Here is a detailed analysis of all Plaid Link sessions between 2025-05-01 and 2025-05-08, including successful conversions and error patterns:


## 1. Conversion Funnel Summary


- Link Opens: 58
- Institution Selected: 29
- Handoffs (successfully completed): 18
...

```

##### Expired tokens 

Access tokens for the MCP server expire after 15 minutes. If the `access_token` passed to the server has expired, requests will return a 401 status code. You can request a new token by either by creating a new one as described above, or by calling the [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) endpoint with the `refresh_token` from the previous step. Both options are valid.

```bash
curl -X POST https://production.plaid.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "YOUR_PRODUCTION_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "grant_type": "refresh_token"
  }'
```

Please note that if your `access_token` has expired, different client libraries will surface that information in different ways. In OpenAI's Python library, for instance, this is raised as a `openai.APIStatusError`:

```undefined
Error code: 424 - {'error': {'message': "Error retrieving tool list from MCP server: 'plaid'. Http status code: 401 (Unauthorized)", 'type': 'external_connector_error', 'param': 'tools', 'code': 'http_error'}}
```

In Anthropic's Python library, this is raised as an `anthropic.BadRequestError:`

```undefined
Error code: 400 - {'type': 'error', 'error': {'type': 'invalid_request_error', 'message': "Invalid authorization token for MCP server 'Plaid Dashboard Server'. Please check your token and try again."}}
```

#### Dashboard MCP tools 

The Dashboard MCP server currently supports the following tools:

##### plaid\_debug\_item 

Diagnose a Plaid item by retrieving related metadata. This tool provides comprehensive information about why an item may not be working properly.

##### plaid\_get\_link\_analytics 

Retrieves Plaid Link analytics data for analyzing user conversion and error rates. This tool can be used to:

*   Analyze Link conversion funnel metrics
*   Track user progression through the Link flow
*   Monitor error rates over time
*   Evaluate Link performance and user experience

Some common use cases for using the `plaid_get_link_analytics` tool include:

*   Monitoring Link conversion rates and identifying drop-offs
*   Analyzing conversion trends over specific time periods
*   Tracking error patterns and frequency (both by type and total via CountEntities)
*   Generating comprehensive Link performance reports
*   Comparing performance across different stages of the Link flow

##### plaid\_get\_usages 

Retrieves usage metrics for Plaid products and services. Use this tool when you need to:

*   Get usage data for specific metrics over a time period
*   Track product usage and consumption
*   Monitor API request volumes

##### plaid\_list\_teams 

List all teams associated with the OAuth token. This is often called automatically by the MCP server to ensure that it is retrieving the data from the appropriate team.

For more details about the tools provided by the Dashboard MCP server, connect to the server using a tool such as the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) .

---


# Resources - Vibe coding tips | Plaid Docs

Vibe coding tips 
=================

#### Get the best results when using AI tools with Plaid 

When using AI coding tools like Cursor or Claude Code with Plaid, following a few best practices can help you get more accurate results.

#### Ensure you have the latest Plaid client library and SDK installed 

If using an AI tool to set up your environment, manually double-check to make sure that the most recent [Plaid client library](https://plaid.com/docs/api/libraries/index.html.md) and, if applicable, the most recent [frontend SDK](https://plaid.com/docs/api/libraries/index.html.md#link-client-sdks) is installed. AI tools love to install outdated versions of these libraries!

When an outdated Plaid library or SDK is installed, not only will you not be able to use the latest Plaid products and features, but the AI tool will tend to use the locally installed documentation, which is itself outdated, and will not discover new products and features.

#### Explicitly include the specific docs pages you want to use in your context 

The Plaid docs site is too large to fit in any commercially available LLM's context windows. You may need to prompt the tool with the specific URLs you want to read docs from, rather than simply having it crawl [https://plaid.com/docs](https://plaid.com/docs) . For best results, use the [LLM-friendly documentation](https://plaid.com/docs/resources/index.html.md#llm-friendly-documentation) .

#### Use the integration overviews, Launch Checklist, and/or vibe coding guides to create a high-level task list 

Most products' documentation includes a high-level integration overview list of steps. ([Example for Plaid Check Consumer Report](https://plaid.com/docs/check/index.html.md#standard-integration-flow) , [example for Transactions](https://plaid.com/docs/transactions/index.html.md#integration-overview) ). Once you have Production access, a more comprehensive and personalized list of steps can be found in the [Launch Center](https://dashboard.plaid.com/developers/launch-center) . For Signal, Transfer, and Transactions, Plaid also has [vibe-coding guides](https://github.com/plaid/ai-coding-toolkit/tree/main/rules) , designed to be used as input to an AI assistant to help it implement these integrations correctly.

Giving these steps to an AI tool can help make sure it implements the right steps. (Of course, none of this is a substitute for making sure you understand the high level steps yourself.)

#### Use sample apps, requests, and responses as context 

Providing your app with existing, known-working sample code from the [Plaid public GitHub](https://github.com/plaid) or sample requests and responses from the [API Reference](https://plaid.com/docs/api/index.html.md) or [Link docs](https://plaid.com/docs/link/index.html.md) to use as context helps LLMs to better discover the correct interfaces for Plaid API calls. Providing a sample response as context can be particularly helpful when working with endpoints that have complex and deeply nested responses, like those used by Income or Consumer Report. (Providing the OpenAPI specification as context does not work as well as providing a JSON response or code sample.)

#### Don't forget Dashboard setup steps 

Many Plaid products require configuration steps in the Dashboard that are not currently exposed to MCP servers and can't be configured by AI. For products like Identity Verification, Monitor, Layer, Signal, and Protect, you will need to use the Dashboard to set up rules and/or templates in order for your integration to work.

#### Ensure you are using the correct test data 

Several Plaid products, especially Identity Verification, require specific test inputs and configurations in Sandbox to receive a successful result, a fact which AI coding tools often miss. Make sure to read the testing documentation for the product you're building and that the test data sent by your app is consistent with the test data expected by Plaid.

---


# Sandbox - Overview | Plaid Docs

Sandbox Overview 
=================

#### Use the Sandbox to quickly develop and test your app 

[API Reference](https://plaid.com/docs/api/sandbox/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md)

#### Sandbox overview 

The Plaid Sandbox is a free and fully-featured environment for application development and testing. All Plaid functionality of both the Plaid API and Plaid Link is supported in the Sandbox environment. A variety of [test accounts](https://plaid.com/docs/sandbox/test-credentials/index.html.md) and [institutions](https://plaid.com/docs/sandbox/institutions/index.html.md) are available to test against, and you can create an unlimited number of test Items. Sandbox API keys can be obtained in the [Plaid Dashboard](https://dashboard.plaid.com) .

The Sandbox environment provides capabilities for testing core use cases, but does not reflect the full scope and complexity of data that can exist in Production. After testing in Sandbox, it is recommended to test in Production or [Limited Production](https://plaid.com/docs/sandbox/index.html.md#testing-with-live-data-using-limited-production) to ensure your application can handle [institution-specific behaviors](https://plaid.com/docs/link/oauth/index.html.md#institution-specific-behaviors) and real-world data before launching.

#### Using Sandbox 

The Sandbox can be reached by sending HTTPS POST requests to the endpoints on the `sandbox.plaid.com` domain. In order to use the Sandbox with a client library, specify Sandbox as your environment when initializing.

The default username/password combination for all Sandbox institutions is `user_good` / `pass_good`.

Most products can be immediately tested in Sandbox with no extra configuration. Some products, such as Payment Initiation (UK and Europe), may require your account be specially enabled. If the product you want to test against is not available in Sandbox, file a request for access ticket via the [Dashboard](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Bypassing Link 

Because the Link UI can and will change from time to time, it is not recommended to write automated end-to-end tests that exercise the Link UI. You should always bypass Link if you are writing an automated test suite that can block your build.

When doing repeated manual tests, or for writing automated tests against Sandbox, completing the Link flow may be impractical. As an alternative, you can also create Items in Sandbox via the API, using a special Sandbox-only endpoint, [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) . This endpoint allows you to generate a `public_token` for an arbitrary institution ID, initial products, and test credentials.

#### Simulating data and events 

The Sandbox provides rich test data, as well as the ability to [generate your own test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) . You can also simulate a number of scenarios for testing in Sandbox. Some of the most common Sandbox scenarios are listed below. For additional product-specific testing scenarios, see the documentation for the specific product you are using, or [Test credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) .

##### ITEM\_LOGIN\_REQUIRED 

[Update mode](https://plaid.com/docs/link/update-mode/index.html.md) in Link is used to handle user logins that have become invalid (for example, due to the user changing their password at their financial institution). An Item that needs to be handled via update mode will enter the `ITEM_LOGIN_REQUIRED` error state. To test your update mode flow in Sandbox, you can use the [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) endpoint to force an Item into this state. Sandbox Items will also automatically enter the `ITEM_LOGIN_REQUIRED` state 30 days after being created.

An example of using update mode and testing in Sandbox can be found in the [Plaid Pattern](https://github.com/plaid/pattern) sample app. [Items.js](https://github.com/plaid/pattern/blob/master/server/routes/items.js#L195) illustrates how to incorporate the handling and testing of update mode using the [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) endpoint.

##### Instant Match and micro-deposit-based Auth 

While the standard Instant Auth flow does not require special configuration to test, the additional Auth flows such as Instant Match, Same-day micro-deposits, and Automated micro-deposits require more complex steps such as verifying micro-deposits or routing numbers. The Sandbox environment provides several test institutions and endpoints that can be used to verify these flows. For more details, see [Testing Auth flows](https://plaid.com/docs/auth/coverage/testing/index.html.md) .

##### Returning user experience 

The Link returning user experience (formerly known as Remember Me) can be tested in Sandbox with several seeded phone numbers. More details can be found at [Testing returning user flow in Sandbox](https://plaid.com/docs/link/returning-user/index.html.md#testing-in-sandbox) .

##### Transactions updates 

To simulate updating transactions, see [Testing pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#testing-pending-and-posted-transactions) .

##### Webhooks 

Plaid provides a special Sandbox-only endpoint, [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) , that can be used to trigger a number of webhooks on demand, allowing you to test that you are receiving webhooks successfully. Webhooks specific to the Income and Transfer products can be sent using the [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) and [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) endpoints.

All webhooks that would be fired in Production will also fire in Sandbox, except when using the Transfer product.

#### Sandbox MCP server 

Plaid has a [Sandbox MCP server](https://github.com/plaid/ai-coding-toolkit/tree/main/sandbox) , which, when run locally, allows your AI-powered agent to call many of these Sandbox endpoints, letting you [trigger webhooks](https://plaid.com/docs/sandbox/index.html.md#webhooks) or [create public tokens](https://plaid.com/docs/sandbox/index.html.md#bypassing-link) to bypass Link.

#### Testing with live data using Limited Production 

To use Link with bank data in Production or Limited Production in the US or Canada, all customers who created accounts after October 31, 2024 must [select a use case description](https://dashboard.plaid.com/link/data-transparency-v5) from the Link Customization section of the Dashboard.

Prior to obtaining Production access, you can make free API calls using live data in Limited Production. In Limited Production, the following restrictions apply:

*   There is a cap on the number of API calls you can make for each product. Both failed and successful API calls count against this cap. API calls that do not relate to a specific product (such as [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) ) do not count against this cap.
*   There is a cap on the total number of Items you can create, unless you have full Production access for at least one product.
*   You cannot access certain major financial institutions, including Bank of America, Chase, and Wells Fargo, unless you have full Production access for at least one product and have also completed the OAuth registration process.
*   The following products are supported in Limited Production: Assets, Auth, Balance, Identity (including Identity Match), Income, Investments, Liabilities, Payment Initiation, Transactions (including Transactions Refresh and Recurring Transactions), and Enrich. To test other products with live data, request Production access.
*   If testing Payment Initiation in Limited Production, limitations on the type and quantity of payments apply. For details, see [Testing Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md#testing-payment-initiation) .

To remove the limits on your Limited Production access, apply for full Production access. Once you have full Production access for a product, usage limits for that product will be removed from your account. If you have any free API calls remaining, as long as you are direct customer of Plaid, you can continue to use them after receiving Production access; once those credits have been used up, your usage will be billed as normal Production traffic. If you are _not_ a direct customer of Plaid and instead are accessing Plaid via a reseller partner, your free API credits will expire once you receive full Production access.

If you add a subscription-billed product to an Item in Limited Production (for example, by creating an Item initialized with Transactions, Investments, or Liabilities), you will not be charged for that subscription unless you continue to use the Item after using up your free API requests and receiving full Production access.

If you require additional API calls in Limited Production to evaluate a product, file a Support ticket.

#### Differences between Sandbox and Production 

Aside from the fact that Sandbox uses test data and has [special endpoints](https://plaid.com/docs/api/sandbox/index.html.md) that can be used, Sandbox has the following special attributes:

*   Does not always reflect institution-specific behaviors and quirks. For example, institutions that do not return pending transactions in Production may return pending transactions in Sandbox. Certain institution-specific behaviors may be tested using [Sandbox test institutions](https://plaid.com/docs/sandbox/institutions/index.html.md) .
*   Does not send emails or text messages, such as confirmation emails after a user has linked an account, or text message reminders for the micro-deposit flow.
*   Does not require a use case to be set, even if you are enrolled in [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) .
*   Allows `http` for redirect URIs, while Production requires `https`.
*   Does not perform any OCR or image processing. To test flows that require these, such as Identity Verification Selfie Checks or Document Income, see the testing section for the specific product you are testing.
*   Sandbox data is not always based on a consistent data source across different API calls, especially across different products. For example, Sandbox transaction history may show income and outflow inconsistent with the balance shown on the account, and some products, like Signal, generate random results in Sandbox. Triggering a transfer using a Transfer endpoint will not cause that transaction to show up when calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) or change the balance of the account when calling [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) .
*   Sandbox may not show the latest updates to the Link UI until those updates have been rolled out to all eligible customers. This may occasionally result in temporary discrepancies between the Sandbox Link UI and the Production Link UI.
*   In the OAuth flow, Sandbox will not enforce the checkboxes for "Select additional information you want to share" and will behave as though all boxes in that section are checked.

One exception to the rule that Sandbox does not use real data is Monitor. While Identity Verification checks cannot be made against real databases in Sandbox, Sandbox does use real Monitor watchlists, although they may not be as up-to-date as the watchlists used in Production.

---


# Sandbox - Test credentials | Plaid Docs

Sandbox test credentials 
=========================

#### Simulate different flows using Sandbox credentials 

When using special Sandbox test credentials described on this page (other than `user_good` / `pass_good`), use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) flow or a non-OAuth test institution, such as First Platypus Bank (`ins_109508`). Special test credentials may be ignored when using the Sandbox Link OAuth flow.

#### Sandbox simple test credentials 

Use the username `user_good` and password `pass_good`.

These provide basic account access.

#### Transactions testing credentials 

Use the username `user_transactions_dynamic` and any password. For persona-based testing, use `user_ewa_user`, `user_yuppie`, or `user_small_business`.

These credentials have realistic transaction history and may update transactions and fire webhooks when [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) is called. For more details, including information on how often new transactions are triggered or how to add your own custom transactions, see [Testing Transactions in Sandbox](https://plaid.com/docs/transactions/index.html.md#testing-transactions-in-sandbox) and [testing pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#testing-pending-and-posted-transactions) .

#### Auth micro-deposit testing credentials 

Use the username `user_good` and the password `microdeposits_good`.

For more details, see [Institution details for Auth testing](https://plaid.com/docs/sandbox/institutions/index.html.md#institution-details-for-auth-testing) .

#### Credit and Income testing credentials 

Plaid provides a variety of pre-populated test users designed for use for Bank Income and other underwriting-related products.

| Username | Password | Description |
| --- | --- | --- |
| `user_bank_income` | `{}` | User with wide variety of income streams of different types |
| `user_credit_bonus` | Any | Has two salary streams: one with bonuses included in the paycheck, one with bonuses as separate transactions |
| `user_credit_joint_account` | Any | Has two salary streams and two identities on the account |
| `user_credit_profile_poor` | Any | Net loss cash flow over time, no consistent source of income |
| `user_credit_profile_good` | Any | Neutral cash flow over time, multiple gig economy income streams |
| `user_credit_profile_excellent` | Any | Positive cash flow over time, high salary-based income with secondary rental income stream |
| `user_prism_1` through `user_prism_10` | Any | For testing Partner Insights reports, these users return a variety of consistent partner insights values |

Plaid also provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) designed specifically for testing credit products; look in the **income** directory for credit-specific users. You can modify these users as you need. For instructions, see [Custom users](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) .

For details on testing Bank Income with custom data, see [Testing Bank Income](https://plaid.com/docs/income/bank-income/index.html.md#testing-bank-income) .

#### Monitor and Identity Verification testing users 

Monitor and Identity Verification have product-specific Sandbox users that can be used for testing. For more details, see [Testing Monitor](https://plaid.com/docs/monitor/index.html.md#testing-monitor) and [Testing Identity Verification](https://plaid.com/docs/identity-verification/testing/index.html.md) .

#### Sandbox multi-factor credentials 

You can trigger any multi-factor authentication (MFA) flow that Plaid supports when creating an `Item` by using username `user_good` and modifying the password.

Bank of America and U.S. Bank cannot be used as test institutions when triggering MFA flows with modified passwords. Instead, these banks will always launch on Sandbox with an MFA flow.

##### Multi-factor device OTP 

```python
username: 'user_good'
password: 'mfa_device'


# Code for all devices: 1234
code: 1234
```

##### Multi-factor questions 

```python
# n-rounds of m-questions per round, where 0 <= i, j < 9
username: 'user_good'
password: 'mfa_questions__'


# answer__, for j-th question in i-th round.
answer: 'answer__'
```

##### __Multi-factor selections__ 

__`username: 'user_good' password: 'mfa_selections'   answer: 'Yes'`__

__`# n-rounds of m-questions with o-answers per question # 0 < n, m < 10 and 2 <= o < 10 username: 'user_good' password: 'mfa_selections___'   # answer___0, for m-th question in n-th round. answer: 'answer_1_1_0'`__

#### __ReCAPTCHA testing credentials__ 

__You may trigger a reCAPTCHA in Plaid Link in the Sandbox environment by customizing the test account password. Possible values are `good` or `bad`. A value of `good` will result in successful Item creation and `bad` will result in a `RECAPTCHA_BAD` error to simulate a failed reCAPTCHA. Both values require the reCAPTCHA to be manually solved within Plaid Link.__

__`username: user_good password: {"recaptcha":"bad"}`__

#### __Error testing credentials__ 

__You can trigger several `ITEM_ERROR` or `INSTITUTION_ERROR` errors that you may encounter when creating an Item by using username `user_good` and modifying the password.__

__`error_[ERROR_CODE]`__

__For example, the password `error_ITEM_LOCKED` allows you to simulate an `ITEM_LOCKED` error.__

__Note that error testing credentials are not compatible with institutions that use OAuth. If you are not sure whether an institution uses OAuth flows, see the list of [Sandbox institutions](https://plaid.com/docs/sandbox/institutions/index.html.md) to find an institution that is guaranteed not to use OAuth.__

__The list of errors that can be simulated in this way is below:__

__`"COUNTRY_NOT_SUPPORTED" "INSTITUTION_DOWN" "INSTITUTION_NOT_RESPONDING" "INSTITUTION_NO_LONGER_SUPPORTED" "INSUFFICIENT_CREDENTIALS" "INTERNAL_SERVER_ERROR" "INVALID_CREDENTIALS" "INVALID_MFA" "INVALID_SEND_METHOD" "ITEM_LOCKED" "ITEM_NOT_SUPPORTED" "MFA_NOT_SUPPORTED" "NO_ACCOUNTS" "PAYMENT_INVALID_RECIPIENT" "USER_INPUT_TIMEOUT" "USER_SETUP_REQUIRED"`__

__You can test several other OAuth-specific Link errors via the drop-down selector on the First Platypus OAuth screen after selecting any OAuth institution. The list of errors that can be simulated in this way is below:__

__`"INSUFFICIENT_CREDENTIALS" "ACCESS_NOT_GRANTED" "NO_AUTH_ACCOUNTS"`__

#### __Link Recovery testing credentials__ 

__See [Testing Link Recovery](https://plaid.com/docs/link/link-recovery/index.html.md#testing-link-recovery) .__

---


# Sandbox - Customize test data | Plaid Docs

Create Sandbox test data 
=========================

#### Use Sandbox accounts to create rich test data for Plaid products 

[Prefer to learn by watching? Check out this quick video guide to Custom Sandbox Users](https://www.youtube.com/watch?v=viSyB5nww_s)

#### Customize Sandbox account data 

In addition to a set of pre-populated [Sandbox test users](https://plaid.com/docs/sandbox/test-credentials/index.html.md) , the Sandbox environment also provides the ability to create custom user accounts, which can be used in conjunction with [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) or Plaid Link to generate custom Sandbox data, or in conjunction with Plaid Link to test Link flows in the Sandbox.

Using these accounts, you can create your own testing data for the Assets, Auth, Balance, Identity, Investments, Liabilities, and Transactions products. You can also simulate an account with regular income or one that makes regular loan payments. For Link testing, custom accounts support multi-factor authentication, reCAPTCHA, and Link error flows.

To customize testing data for Document Income, see [Testing Document Income](https://plaid.com/docs/income/document-income/index.html.md#testing-document-income) .

\=\*=\*=\*=

#### Configuring the custom user account 

Custom user accounts can be configured and accessed in two ways. The easiest (and recommended) method is by using the [Sandbox Users](https://dashboard.plaid.com/developers/sandbox?tab=testUsers) tool, located in the Plaid Dashboard under Developers -> Sandbox. Set the username and [configuration object](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuration-object-schema) in the Dashboard, then go through the Link flow on Sandbox with that username and any non-empty password. You can also use [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) with `options.override_username` and `options.override_password` to create a public token for a custom user account while bypassing Link. Alternatively, you can log into Sandbox with the username `user_custom` and provide the [configuration object](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuration-object-schema) as the password.

To aid in testing, Plaid maintains a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) of pre-created custom user accounts that some users have found helpful.

##### Limitations of the custom user account 

Very large configuration objects (larger than approximately 55kb, or approximately 250 transactions) are not supported and may cause the Link attempt to fail.

Using more than ten accounts on a single custom user is not supported and will cause the Link attempt to fail.

If you are using Consumer Report by Plaid Check, to use a custom user, you must click "add new account" in the Link flow rather than using one of the existing banks. Using an existing bank in the Plaid Passport flow will skip the ability to enter a custom username.

At OAuth institutions, custom users may not work properly: certain less frequently used customized fields may be overridden by the default values after the Link flow has completed, or the login may fail. If this occurs, retry the configuration using a non-OAuth institution, such as First Gingham Credit Union or First Platypus Bank.

\=\*=\*=\*=

#### Configuration object schema 

Custom test accounts are configured with a JSON configuration object formulated according to the schema below. All top level fields are optional. Sending an empty object as a configuration will result in an account configured with random balances and transaction history.

**Properties**

[version](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-version)

string

The version of the password schema to use, possible values are 1 or 2. The default value is 2. You should only specify 1 if you know it is necessary for your test suite.

[seed](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-seed)

string

A seed, in the form of a string, that will be used to randomly generate account and transaction data, if this data is not specified using the `override_accounts` argument. If no seed is specified, the randomly generated data will be different each time.  
Note that transactions data is generated relative to the Item's creation date. Different Items created on different dates with the same seed for transactions data will have different dates for the transactions. The number of days between each transaction and the Item creation will remain constant. For example, an Item created on December 15 might show a transaction on December 14. An Item created on December 20, using the same seed, would show that same transaction occurring on December 19.

[override\_accounts](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts)

\[object\]

An array of account overrides to configure the accounts for the Item. By default, if no override is specified, transactions and account data will be randomly generated based on the account type and subtype, and other products will have fixed or empty data.

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-type)

string

`investment:` Investment account.  
`credit:` Credit card  
`depository:` Depository account  
`loan:` Loan account  
`payroll:` Payroll account  
`other:` Non-specified account type  
See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes.  
  

Possible values: `investment`, `credit`, `depository`, `loan`, `payroll`, `other`

[subtype](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-subtype)

string

See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes.  
  

Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity`

[starting\_balance](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-starting-balance)

number

If provided, the account will start with this amount as the current balance.  
  

Format: `double`

[force\_available\_balance](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-force-available-balance)

number

If provided, the account will always have this amount as its available balance, regardless of current balance or changes in transactions over time.  
  

Format: `double`

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-currency)

string

ISO-4217 currency code. If provided, the account will be denominated in the given currency. Transactions will also be in this currency by default.

[meta](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-meta)

object

Allows specifying the metadata of the test account

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-meta-name)

string

The account's name

[official\_name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-meta-official-name)

string

The account's official name

[limit](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-meta-limit)

number

The account's limit  
  

Format: `double`

[mask](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-meta-mask)

string

The account's mask. Should be an empty string or a string of 2-4 alphanumeric characters. This allows you to model a mask which does not match the account number (such as with a virtual account number).  
  

Pattern: `^$|^[A-Za-z0-9]{2,4}$`

[numbers](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers)

object

Account and bank identifier number data used to configure the test account. All values are optional.

[account](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-account)

string

Will be used for the account number.

[ach\_routing](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-ach-routing)

string

Must be a valid ACH routing number. To test `/transfer/capabilities/get`, set this to 322271627 to force a `true` result.

[ach\_wire\_routing](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-ach-wire-routing)

string

Must be a valid wire transfer routing number.

[eft\_institution](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-eft-institution)

string

EFT institution number. Must be specified alongside `eft_branch`.

[eft\_branch](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-eft-branch)

string

EFT branch number. Must be specified alongside `eft_institution`.

[international\_bic](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-international-bic)

string

Bank identifier code (BIC). Must be specified alongside `international_iban`.

[international\_iban](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-international-iban)

string

International bank account number (IBAN). If no account number is specified via `account`, will also be used as the account number by default. Must be specified alongside `international_bic`.

[bacs\_sort\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-numbers-bacs-sort-code)

string

BACS sort code

[transactions](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-transactions)

\[object\]

Specify the list of transactions on the account.

[date\_transacted](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-transactions-date-transacted)

string

The date of the transaction, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Transactions in Sandbox will move from pending to posted once their transaction date has been reached. If a `date_transacted` is not provided by the institution, a transaction date may be available in the [authorized\_date](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-transactions-authorized-date) field.  
  

Format: `date`

[date\_posted](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-transactions-date-posted)

string

The date the transaction posted, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Posted dates in the past or present will result in posted transactions; posted dates in the future will result in pending transactions.  
  

Format: `date`

[amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-transactions-amount)

number

The transaction amount. Can be negative.  
  

Format: `double`

[description](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-transactions-description)

string

The transaction description.

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-transactions-currency)

string

The ISO-4217 format currency code for the transaction.

[holdings](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings)

object

Specify the holdings on the account.

[institution\_price](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-institution-price)

number

The last price given by the institution for this security  
  

Format: `double`

[institution\_price\_as\_of](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-institution-price-as-of)

string

The date at which `institution_price` was current. Must be formatted as an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) date.  
  

Format: `date`

[cost\_basis](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-cost-basis)

number

The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding).  
  

Format: `double`

[quantity](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-quantity)

number

The total quantity of the asset held, as reported by the financial institution.  
  

Format: `double`

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-currency)

string

Either a valid `iso_currency_code` or `unofficial_currency_code`

[security](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-security)

object

Specify the security associated with the holding or investment transaction. When inputting custom security data to the Sandbox, Plaid will perform post-data-retrieval normalization and enrichment. These processes may cause the data returned by the Sandbox to be slightly different from the data you input. An ISO-4217 currency code and a security identifier (`ticker_symbol`, `cusip`, or `isin`) are required.

[isin](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-security-isin)

string

12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please [request ISIN/CUSIP access here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) .

[cusip](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-security-cusip)

string

9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please [request ISIN/CUSIP access here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) .

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-security-name)

string

A descriptive name for the security, suitable for display.

[ticker\_symbol](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-security-ticker-symbol)

string

The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-holdings-security-currency)

string

Either a valid `iso_currency_code` or `unofficial_currency_code`

[investment\_transactions](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions)

object

Specify the list of investments transactions on the account.

[date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-date)

string

Posting date for the transaction. Must be formatted as an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) date.  
  

Format: `date`

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-name)

string

The institution's description of the transaction.

[quantity](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-quantity)

number

The number of units of the security involved in this transaction. Must be positive if the type is a buy and negative if the type is a sell.  
  

Format: `double`

[price](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-price)

number

The price of the security at which this transaction occurred.  
  

Format: `double`

[fees](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-fees)

number

The combined value of all fees applied to this transaction.  
  

Format: `double`

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-type)

string

The type of the investment transaction. Possible values are: `buy`: Buying an investment `sell`: Selling an investment `cash`: Activity that modifies a cash position `fee`: A fee on the account `transfer`: Activity that modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-currency)

string

Either a valid `iso_currency_code` or `unofficial_currency_code`

[security](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-security)

object

Specify the security associated with the holding or investment transaction. When inputting custom security data to the Sandbox, Plaid will perform post-data-retrieval normalization and enrichment. These processes may cause the data returned by the Sandbox to be slightly different from the data you input. An ISO-4217 currency code and a security identifier (`ticker_symbol`, `cusip`, or `isin`) are required.

[isin](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-security-isin)

string

12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please [request ISIN/CUSIP access here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) .

[cusip](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-security-cusip)

string

9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please [request ISIN/CUSIP access here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) .

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-security-name)

string

A descriptive name for the security, suitable for display.

[ticker\_symbol](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-security-ticker-symbol)

string

The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-investment-transactions-security-currency)

string

Either a valid `iso_currency_code` or `unofficial_currency_code`

[identity](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity)

object

Data about the owner or owners of an account. Any fields not specified will be filled in with default Sandbox information.

[names](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-names)

\[string\]

A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. Note that the same name data will be used for all accounts associated with an Item.

[phone\_numbers](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-phone-numbers)

\[object\]

A list of phone numbers associated with the account.

[data](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-phone-numbers-data)

string

The phone number.

[primary](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-phone-numbers-primary)

boolean

When `true`, identifies the phone number as the primary number on an account.

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-phone-numbers-type)

string

The type of phone number.  
  

Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other`

[emails](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-emails)

\[object\]

A list of email addresses associated with the account.

[data](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-emails-data)

string

The email address.

[primary](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-emails-primary)

boolean

When `true`, identifies the email address as the primary email on an account.

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-emails-type)

string

The type of email account as described by the financial institution.  
  

Possible values: `primary`, `secondary`, `other`

[addresses](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses)

\[object\]

Data about the various addresses associated with the account.

[data](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-data)

object

Data about the components comprising an address.

[city](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-data-city)

string

The full city name

[region](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-data-region)

string

The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"`

[street](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-data-street)

string

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

[postal\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-data-postal-code)

string

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

[country](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-data-country)

string

The ISO 3166-1 alpha-2 country code

[primary](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-identity-addresses-primary)

boolean

When `true`, identifies the address as the primary address on an account.

[liability](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability)

object

Used to configure Sandbox test data for the Liabilities product

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-type)

string

The type of the liability object, either `credit` or `student`. Mortgages are not currently supported in the custom Sandbox.

[purchase\_apr](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-purchase-apr)

number

The purchase APR percentage value. For simplicity, this is the only interest rate used to calculate interest charges. Can only be set if `type` is `credit`.  
  

Format: `double`

[cash\_apr](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-cash-apr)

number

The cash APR percentage value. Can only be set if `type` is `credit`.  
  

Format: `double`

[balance\_transfer\_apr](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-balance-transfer-apr)

number

The balance transfer APR percentage value. Can only be set if `type` is `credit`.  
  

Format: `double`

[special\_apr](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-special-apr)

number

The special APR percentage value. Can only be set if `type` is `credit`.  
  

Format: `double`

[last\_payment\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-last-payment-amount)

number

Override the `last_payment_amount` field. Can only be set if `type` is `credit`.  
  

Format: `double`

[minimum\_payment\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-minimum-payment-amount)

number

Override the `minimum_payment_amount` field. Can only be set if `type` is `credit` or `student`.  
  

Format: `double`

[is\_overdue](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-is-overdue)

boolean

Override the `is_overdue` field

[origination\_date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-origination-date)

string

The date on which the loan was initially lent, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Can only be set if `type` is `student`.  
  

Format: `date`

[principal](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-principal)

number

The original loan principal. Can only be set if `type` is `student`.  
  

Format: `double`

[nominal\_apr](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-nominal-apr)

number

The interest rate on the loan as a percentage. Can only be set if `type` is `student`.  
  

Format: `double`

[interest\_capitalization\_grace\_period\_months](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-interest-capitalization-grace-period-months)

number

If set, interest capitalization begins at the given number of months after loan origination. By default interest is never capitalized. Can only be set if `type` is `student`.

[repayment\_model](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-repayment-model)

object

Student loan repayment information used to configure Sandbox test data for the Liabilities product

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-repayment-model-type)

string

The only currently supported value for this field is `standard`.

[non\_repayment\_months](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-repayment-model-non-repayment-months)

number

Configures the number of months before repayment starts.

[repayment\_months](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-repayment-model-repayment-months)

number

Configures the number of months of repayments before the loan is paid off.

[expected\_payoff\_date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-expected-payoff-date)

string

Override the `expected_payoff_date` field. Can only be set if `type` is `student`.  
  

Format: `date`

[guarantor](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-guarantor)

string

Override the `guarantor` field. Can only be set if `type` is `student`.

[is\_federal](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-is-federal)

boolean

Override the `is_federal` field. Can only be set if `type` is `student`.

[loan\_name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-loan-name)

string

Override the `loan_name` field. Can only be set if `type` is `student`.

[loan\_status](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-loan-status)

object

An object representing the status of the student loan

[end\_date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-loan-status-end-date)

string

The date until which the loan will be in its current status. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD).  
  

Format: `date`

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-loan-status-type)

string

The status type of the student loan  
  

Possible values: `cancelled`, `charged off`, `claim`, `consolidated`, `deferment`, `delinquent`, `discharged`, `extension`, `forbearance`, `in grace`, `in military`, `in school`, `not fully disbursed`, `other`, `paid in full`, `refunded`, `repayment`, `transferred`, `pending idr`

[payment\_reference\_number](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-payment-reference-number)

string

Override the `payment_reference_number` field. Can only be set if `type` is `student`.

[repayment\_plan\_description](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-repayment-plan-description)

string

Override the `repayment_plan.description` field. Can only be set if `type` is `student`.

[repayment\_plan\_type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-repayment-plan-type)

string

Override the `repayment_plan.type` field. Can only be set if `type` is `student`. Possible values are: `"extended graduated"`, `"extended standard"`, `"graduated"`, `"income-contingent repayment"`, `"income-based repayment"`, `"income-sensitive repayment"`, `"interest only"`, `"other"`, `"pay as you earn"`, `"revised pay as you earn"`, `"standard"`, or `"saving on a valuable education"`.

[sequence\_number](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-sequence-number)

string

Override the `sequence_number` field. Can only be set if `type` is `student`.

[servicer\_address](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address)

object

A physical mailing address.

[data](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-data)

object

Data about the components comprising an address.

[city](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-data-city)

string

The full city name

[region](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-data-region)

string

The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"`

[street](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-data-street)

string

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

[postal\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-data-postal-code)

string

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

[country](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-data-country)

string

The ISO 3166-1 alpha-2 country code

[primary](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-liability-servicer-address-primary)

boolean

When `true`, identifies the address as the primary address on an account.

[inflow\_model](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-inflow-model)

object

The `inflow_model` allows you to model a test account that receives regular income or make regular payments on a loan. Any transactions generated by the `inflow_model` will appear in addition to randomly generated test data or transactions specified by `override_accounts`.

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-inflow-model-type)

string

Inflow model. One of the following:  
`none`: No income  
`monthly-income`: Income occurs once per month `monthly-balance-payment`: Pays off the balance on a liability account at the given statement day of month.  
`monthly-interest-only-payment`: Makes an interest-only payment on a liability account at the given statement day of month.  
Note that account types supported by Liabilities will accrue interest in the Sandbox. The types impacted are account type `credit` with subtype `credit` or `paypal`, and account type `loan` with subtype `student` or `mortgage`.

[income\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-inflow-model-income-amount)

number

Amount of income per month. This value is required if `type` is `monthly-income`.  
  

Format: `double`

[payment\_day\_of\_month](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-inflow-model-payment-day-of-month)

number

Number between 1 and 28, or `last` meaning the last day of the month. The day of the month on which the income transaction will appear. The name of the income transaction. This field is required if `type` is `monthly-income`, `monthly-balance-payment` or `monthly-interest-only-payment`.

[transaction\_name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-inflow-model-transaction-name)

string

The name of the income transaction. This field is required if `type` is `monthly-income`, `monthly-balance-payment` or `monthly-interest-only-payment`.

[statement\_day\_of\_month](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-inflow-model-statement-day-of-month)

string

Number between 1 and 28, or `last` meaning the last day of the month. The day of the month on which the balance is calculated for the next payment. The name of the income transaction. This field is required if `type` is `monthly-balance-payment` or `monthly-interest-only-payment`.

[income](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income)

object

Specify payroll data on the account.

[paystubs](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs)

\[object\]

A list of paystubs associated with the account.

[employer](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer)

object

The employer on the paystub.

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-name)

string

The name of the employer.

[address](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-address)

object

The address of the employer.

[city](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-address-city)

string

The full city name.

[region](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-address-region)

string

The region or state Example: `"NC"`

[street](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-address-street)

string

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

[postal\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-address-postal-code)

string

5 digit postal code.

[country](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employer-address-country)

string

The country of the address.

[employee](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee)

object

The employee on the paystub.

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-name)

string

The name of the employee.

[address](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-address)

object

The address of the employee.

[city](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-address-city)

string

The full city name.

[region](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-address-region)

string

The region or state Example: `"NC"`

[street](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-address-street)

string

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

[postal\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-address-postal-code)

string

5 digit postal code.

[country](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-address-country)

string

The country of the address.

[marital\_status](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-marital-status)

string

Marital status of the employee - either `single` or `married`.  
  

Possible values: `single`, `married`

[taxpayer\_id](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-taxpayer-id)

object

Taxpayer ID of the individual receiving the paystub.

[id\_type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-taxpayer-id-id-type)

string

Type of ID, e.g. 'SSN'

[id\_mask](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-employee-taxpayer-id-id-mask)

string

ID mask; i.e. last 4 digits of the taxpayer ID

[net\_pay](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-net-pay)

object

An object representing information about the net pay amount on the paystub.

[description](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-net-pay-description)

string

Description of the net pay

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-net-pay-currency)

string

The ISO-4217 currency code of the net pay.

[ytd\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-net-pay-ytd-amount)

number

The year-to-date amount of the net pay  
  

Format: `double`

[deductions](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions)

object

An object with the deduction information found on a paystub.

[breakdown](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-breakdown)

\[object\]

[current\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-breakdown-current-amount)

number

Raw amount of the deduction  
  

Format: `double`

[description](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-breakdown-description)

string

Description of the deduction line item

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-breakdown-currency)

string

The ISO-4217 currency code of the line item.

[ytd\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-breakdown-ytd-amount)

number

The year-to-date amount of the deduction  
  

Format: `double`

[total](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-total)

object

An object representing the total deductions for the pay period

[current\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-total-current-amount)

number

Raw amount of the deduction  
  

Format: `double`

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-total-currency)

string

The ISO-4217 currency code of the line item.

[ytd\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-deductions-total-ytd-amount)

number

The year-to-date total amount of the deductions  
  

Format: `double`

[earnings](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings)

object

An object representing both a breakdown of earnings on a paystub and the total earnings.

[breakdown](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown)

\[object\]

[canonical\_description](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-canonical-description)

string

Commonly used term to describe the earning line item.  
  

Possible values: `BONUS`, `COMMISSION`, `OVERTIME`, `PAID TIME OFF`, `REGULAR PAY`, `VACATION`, `BASIC ALLOWANCE HOUSING`, `BASIC ALLOWANCE SUBSISTENCE`, `OTHER`, `null`

[current\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-current-amount)

number

Raw amount of the earning line item.  
  

Format: `double`

[description](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-description)

string

Description of the earning line item.

[hours](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-hours)

number

Number of hours applicable for this earning.

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-currency)

string

The ISO-4217 currency code of the line item.

[rate](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-rate)

number

Hourly rate applicable for this earning.  
  

Format: `double`

[ytd\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-breakdown-ytd-amount)

number

The year-to-date amount of the deduction.  
  

Format: `double`

[total](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-total)

object

An object representing both the current pay period and year to date amount for an earning category.

[hours](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-total-hours)

number

Total number of hours worked for this pay period

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-total-currency)

string

The ISO-4217 currency code of the line item

[ytd\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-earnings-total-ytd-amount)

number

The year-to-date amount for the total earnings  
  

Format: `double`

[pay\_period\_details](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details)

object

Details about the pay period.

[check\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-check-amount)

number

The amount of the paycheck.  
  

Format: `double`

[distribution\_breakdown](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown)

\[object\]

[account\_name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown-account-name)

string

Name of the account for the given distribution.

[bank\_name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown-bank-name)

string

The name of the bank that the payment is being deposited to.

[current\_amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown-current-amount)

number

The amount distributed to this account.  
  

Format: `double`

[currency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown-currency)

string

The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null.

[mask](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown-mask)

string

The last 2-4 alphanumeric characters of an account's official account number.

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-distribution-breakdown-type)

string

Type of the account that the paystub was sent to (e.g. 'checking').

[end\_date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-end-date)

string

The pay period end date, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format: "yyyy-mm-dd".  
  

Format: `date`

[gross\_earnings](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-gross-earnings)

number

Total earnings before tax/deductions.  
  

Format: `double`

[pay\_date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-pay-date)

string

The date on which the paystub was issued, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd").  
  

Format: `date`

[pay\_frequency](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-pay-frequency)

string

The frequency at which an individual is paid.  
  

Possible values: `PAY_FREQUENCY_UNKNOWN`, `PAY_FREQUENCY_WEEKLY`, `PAY_FREQUENCY_BIWEEKLY`, `PAY_FREQUENCY_SEMIMONTHLY`, `PAY_FREQUENCY_MONTHLY`, `null`

[pay\_day](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-pay-day)

deprecated, string

The date on which the paystub was issued, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd").  
  

Format: `date`

[start\_date](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-paystubs-pay-period-details-start-date)

string

The pay period start date, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format: "yyyy-mm-dd".  
  

Format: `date`

[w2s](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s)

\[object\]

A list of w2s associated with the account.

[employer](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer)

object

The employer on the paystub.

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-name)

string

The name of the employer.

[address](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-address)

object

The address of the employer.

[city](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-address-city)

string

The full city name.

[region](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-address-region)

string

The region or state Example: `"NC"`

[street](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-address-street)

string

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

[postal\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-address-postal-code)

string

5 digit postal code.

[country](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-address-country)

string

The country of the address.

[employee](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee)

object

The employee on the paystub.

[name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-name)

string

The name of the employee.

[address](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-address)

object

The address of the employee.

[city](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-address-city)

string

The full city name.

[region](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-address-region)

string

The region or state Example: `"NC"`

[street](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-address-street)

string

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

[postal\_code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-address-postal-code)

string

5 digit postal code.

[country](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-address-country)

string

The country of the address.

[marital\_status](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-marital-status)

string

Marital status of the employee - either `single` or `married`.  
  

Possible values: `single`, `married`

[taxpayer\_id](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-taxpayer-id)

object

Taxpayer ID of the individual receiving the paystub.

[id\_type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-taxpayer-id-id-type)

string

Type of ID, e.g. 'SSN'

[id\_mask](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employee-taxpayer-id-id-mask)

string

ID mask; i.e. last 4 digits of the taxpayer ID

[tax\_year](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-tax-year)

string

The tax year of the W2 document.

[employer\_id\_number](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-employer-id-number)

string

An employer identification number or EIN.

[wages\_tips\_other\_comp](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-wages-tips-other-comp)

string

Wages from tips and other compensation.

[federal\_income\_tax\_withheld](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-federal-income-tax-withheld)

string

Federal income tax withheld for the tax year.

[social\_security\_wages](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-social-security-wages)

string

Wages from social security.

[social\_security\_tax\_withheld](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-social-security-tax-withheld)

string

Social security tax withheld for the tax year.

[medicare\_wages\_and\_tips](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-medicare-wages-and-tips)

string

Wages and tips from medicare.

[medicare\_tax\_withheld](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-medicare-tax-withheld)

string

Medicare tax withheld for the tax year.

[social\_security\_tips](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-social-security-tips)

string

Tips from social security.

[allocated\_tips](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-allocated-tips)

string

Allocated tips.

[box\_9](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-box-9)

string

Contents from box 9 on the W2.

[dependent\_care\_benefits](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-dependent-care-benefits)

string

Dependent care benefits.

[nonqualified\_plans](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-nonqualified-plans)

string

Nonqualified plans.

[box\_12](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-box-12)

\[object\]

[code](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-box-12-code)

string

W2 Box 12 code.

[amount](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-box-12-amount)

string

W2 Box 12 amount.

[statutory\_employee](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-statutory-employee)

string

Statutory employee.

[retirement\_plan](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-retirement-plan)

string

Retirement plan.

[third\_party\_sick\_pay](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-third-party-sick-pay)

string

Third party sick pay.

[other](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-other)

string

Other.

[state\_and\_local\_wages](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages)

\[object\]

[state](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-state)

string

State associated with the wage.

[employer\_state\_id\_number](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-employer-state-id-number)

string

State identification number of the employer.

[state\_wages\_tips](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-state-wages-tips)

string

Wages and tips from the specified state.

[state\_income\_tax](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-state-income-tax)

string

Income tax from the specified state.

[local\_wages\_tips](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-local-wages-tips)

string

Wages and tips from the locality.

[local\_income\_tax](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-local-income-tax)

string

Income tax from the locality.

[locality\_name](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-override-accounts-income-w2s-state-and-local-wages-locality-name)

string

Name of the locality.

[mfa](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-mfa)

object

Specifies the multi-factor authentication settings to use with this test account

[type](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-mfa-type)

string

Possible values are `device`, `selections`, or `questions`.  
If value is `device`, the MFA answer is `1234`.  
If value is `selections`, the MFA answer is always the first option.  
If value is `questions`, the MFA answer is `answer_<i>_<j>` for the j-th question in the i-th round, starting from 0. For example, the answer to the first question in the second round is `answer_1_0`.

[question\_rounds](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-mfa-question-rounds)

number

Number of rounds of questions. Required if value of `type` is `questions`.

[questions\_per\_round](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-mfa-questions-per-round)

number

Number of questions per round. Required if value of `type` is `questions`. If value of type is `selections`, default value is 2.

[selection\_rounds](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-mfa-selection-rounds)

number

Number of rounds of selections, used if `type` is `selections`. Defaults to 1.

[selections\_per\_question](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-mfa-selections-per-question)

number

Number of available answers per question, used if `type` is `selection`. Defaults to 2.

[recaptcha](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-recaptcha)

string

You may trigger a reCAPTCHA in Plaid Link in the Sandbox environment by using the recaptcha field. Possible values are `good` or `bad`. A value of `good` will result in successful Item creation and `bad` will result in a `RECAPTCHA_BAD` error to simulate a failed reCAPTCHA. Both values require the reCAPTCHA to be manually solved within Plaid Link.

[force\_error](https://plaid.com/docs/sandbox/user-custom/index.html.md#UserCustomPassword-force-error)

string

An error code to force on Item creation. Possible values are:  
`"INSTITUTION_NOT_RESPONDING"` `"INSTITUTION_NO_LONGER_SUPPORTED"` `"INVALID_CREDENTIALS"` `"INVALID_MFA"` `"ITEM_LOCKED"` `"ITEM_LOGIN_REQUIRED"` `"ITEM_NOT_SUPPORTED"` `"INVALID_LINK_TOKEN"` `"MFA_NOT_SUPPORTED"` `"NO_ACCOUNTS"` `"PLAID_ERROR"` `"USER_INPUT_TIMEOUT"` `"USER_SETUP_REQUIRED"`

```json
{
  "seed": "my-seed-string-3",
  "override_accounts": [
    {
      "type": "depository",
      "subtype": "checking",
      "identity": {
        "names": [
          "John Doe"
        ],
        "phone_numbers": [
          {
            "primary": true,
            "type": "home",
            "data": "4673956022"
          }
        ],
        "emails": [
          {
            "primary": true,
            "type": "primary",
            "data": "accountholder0@example.com"
          }
        ],
        "addresses": [
          {
            "primary": true,
            "data": {
              "city": "Malakoff",
              "region": "NY",
              "street": "2992 Cameron Road",
              "postal_code": "14236",
              "country": "US"
            }
          }
        ]
      },
      "transactions": [
        {
          "date_transacted": "2023-10-01",
          "date_posted": "2023-10-03",
          "currency": "USD",
          "amount": 100,
          "description": "1 year Netflix subscription"
        },
        {
          "date_transacted": "2023-10-01",
          "date_posted": "2023-10-02",
          "currency": "USD",
          "amount": 100,
          "description": "1 year mobile subscription"
        }
      ]
    },
    {
      "type": "loan",
      "subtype": "student",
      "liability": {
        "type": "student",
        "origination_date": "2023-01-01",
        "principal": 10000,
        "nominal_apr": 6.25,
        "loan_name": "Plaid Student Loan",
        "repayment_model": {
          "type": "standard",
          "non_repayment_months": 12,
          "repayment_months": 120
        }
      }
    },
    {
      "type": "credit",
      "subtype": "credit card",
      "starting_balance": 10000,
      "inflow_model": {
        "type": "monthly-interest-only-payment",
        "payment_day_of_month": 15,
        "statement_day_of_month": 13,
        "transaction_name": "Interest Payment"
      },
      "liability": {
        "type": "credit",
        "purchase_apr": 12.9,
        "balance_transfer_apr": 15.24,
        "cash_apr": 28.45,
        "special_apr": 0,
        "last_payment_amount": 500,
        "minimum_payment_amount": 10
      }
    },
    {
      "type": "investment",
      "subtype": "brokerage",
      "investment_transactions": [
        {
          "date": "2023-07-01",
          "name": "buy stock",
          "quantity": 10,
          "price": 10,
          "fees": 20,
          "type": "buy",
          "currency": "USD",
          "security": {
            "ticker_symbol": "PLAID",
            "currency": "USD"
          }
        }
      ],
      "holdings": [
        {
          "institution_price": 10,
          "institution_price_as_of": "2023-08-01",
          "cost_basis": 10,
          "quantity": 10,
          "currency": "USD",
          "security": {
            "ticker_symbol": "PLAID",
            "currency": "USD"
          }
        }
      ]
    },
    {
      "type": "payroll",
      "subtype": "payroll",
      "income": {
        "paystubs": [
          {
            "employer": {
              "name": "Heartland Toy Company"
            },
            "employee": {
              "name": "Chip Hazard",
              "address": {
                "city": "Burbank",
                "region": "CA",
                "street": "411 N Hollywood Way",
                "postal_code": "91505",
                "country": "US"
              }
            },
            "income_breakdown": [
              {
                "type": "regular",
                "rate": 20,
                "hours": 40,
                "total": 800
              },
              {
                "type": "overtime",
                "rate": 30,
                "hours": 6.68,
                "total": 200.39
              }
            ],
            "pay_period_details": {
              "start_date": "2021-05-04",
              "end_date": "2021-05-18",
              "gross_earnings": 1000.39,
              "check_amount": 499.28
            }
          }
        ]
      }
    }
  ]
}
```

---


# Signal - Add Signal to your app | Plaid Docs

Add Plaid Signal to your app 
=============================

#### Learn how to add Plaid Signal support to your application 

In this guide, we'll start from scratch and walk through how to use [Plaid Signal](https://plaid.com/docs/api/products/signal/index.html.md) to perform risk analysis on proposed ACH transactions. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [creating rules](https://plaid.com/docs/signal/add-to-app/index.html.md#creating-rules) .

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item in Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.

##### Create a link\_token 

To require that the institution support Signal, put `signal` in the `products` array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To allow connections from institutions that don't support Signal, put it in the `optional_products` array. For more details, see [Creating Signal Items](https://plaid.com/docs/signal/creating-signal-items/index.html.md) .

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['auth, signal'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access\_token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Adding Signal to existing Items 

If your flow involves adding Signal to existing Items that weren't initialized with Signal in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) flow, call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) on those Items. For more details, see [Creating Signal Items](https://plaid.com/docs/signal/creating-signal-items/index.html.md#adding-signal-to-existing-items) .

```javascript
const prepare_request = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
};


try {
  const prepare_response = await plaidClient.signalPrepare(prepare_request);
  const request_id = prepare_response.data.request_id;
  console.log(request_id);
} catch (error) {
  // handle error
}
```

#### Creating rules 

Now that the authentication and initialization step is out of the way, we can begin using Signal to analyze proposed transactions. Go to the [Signal Rules Dashboard](https://dashboard.plaid.com/signal/risk-profiles) to create rules. For details, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) .

Once you've created your Signal rules, you can evaluate transactions with [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) .

#### Evaluating a proposed transaction 

```javascript
const eval_request = {
  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
  client_transaction_id: 'txn12345',
  amount: 123.45,
  client_user_id: 'user1234',
  user: {
    name: {
      prefix: 'Ms.',
      given_name: 'Jane',
      middle_name: 'Leah',
      family_name: 'Doe',
      suffix: 'Jr.',
    },
    phone_number: '+14152223333',
    email_address: 'jane.doe@example.com',
    address: {
      street: '2493 Leisure Lane',
      city: 'San Matias',
      region: 'CA',
      postal_code: '93405-2255',
      country: 'US',
    },
  },
  device: {
    ip_address: '198.30.2.2',
    user_agent:
      'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1',
  },
  user_present: true,
  ruleset_key: "recommended-risk-rules"
};


try {
  const eval_response = await plaidClient.signalEvaluate(eval_request);
  const result = eval_response.data.ruleset.result;
} catch (error) {
  // handle error
}
```

Based on the `result` of either `accept`, `review`, or `reroute`, proceed with the transfer, review it, or reroute the user to a different payment method.

#### Reporting transaction results 

If the result was `review`, report your final review decision to Plaid using [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) or by uploading a CSV. For more details, see [Reporting decisions and returns](https://plaid.com/docs/signal/reporting-returns/index.html.md) .

```javascript
const decision_report_request = {
  client_transaction_id: 'txn12345',
  initiated: true,
  days_funds_on_hold: 3,
};


try {
  const decision_report_response = await plaidClient.signalDecisionReport(
    decision_report_request,
  );
  const decision_request_id = decision_report_response.data.request_id;
} catch (error) {
  // handle error
}
```

If you allow a transfer that does end up returned, report that result back to Plaid as well. You can do this by calling [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) or by uploading a CSV. For more details, see [Reporting decisions and returns](https://plaid.com/docs/signal/reporting-returns/index.html.md) .

```javascript
const return_report_request = {
  client_transaction_id: 'txn12345',
  return_code: 'R01',
};


try {
  const return_report_response = await plaidClient.signalReturnReport(
    return_report_request,
  );
  const request_id = return_report_response.data.request_id;
  console.log(request_id);
} catch (error) {
  // handle error
}
```

#### Iterate on Signal Rules 

Once you have run Signal in Production and have amassed enough transaction history (a few hundred transactions), you should periodically review the Signal Performance Dashboard and tweak your rulesets as necessary. For more details, see [Tuning your rules](https://plaid.com/docs/signal/signal-rules/index.html.md#tuning-your-rules) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Signal - Creating Signal Items | Plaid Docs

Initialize Plaid Items 
=======================

#### Create Plaid Items to be used with Signal 

#### Creating Plaid Items 

Before evaluating a payment with Signal, your end users need to link a bank account to your app using [Link](https://plaid.com/docs/link/index.html.md) , Plaid's client-side widget. Link will connect the user's bank account and obtain the consent required to perform this evaluation.

See the [Link documentation](https://plaid.com/docs/link/index.html.md) for more details on setting up a Plaid Link session. At a high level, the steps are:

1.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the `auth` and `signal` products.
    
    *   (Recommended) To enable the account for use with Signal, and have Signal utilize whatever data is available, put `signal` in the `optional_products` array.
    *   To require Signal has the maximum data available to it (and reject all Link attempts at institutions that may not provide certain pieces of data), include `signal` in the `products` array.
    *   If you add Signal to the `additional_consented_products` array instead, you may need to call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) later on; see [Adding Signal to existing Items](https://plaid.com/docs/signal/creating-signal-items/index.html.md#adding-signal-to-existing-items) for details.
2.  Initialize Link using the `link_token` created in the previous step. For more details for your specific platform, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . The user will now go through the Link flow.
    
3.  Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token`.
    
4.  Obtain the `account_id` of the account used for the transaction you wish to perform the evaluation on; this can be obtained from the `metadata.accounts` field in the `onSuccess` callback, or by calling [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) or [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) .
    

Once you have your Plaid Item, continue to [evaluate](https://plaid.com/docs/signal/signal-rules/index.html.md) the risk of the transaction.

#### Adding Signal to existing Items 

You may have Items that were not initialized with Signal; for example, if you are adding Signal to an existing Plaid integration. In this case, for best results, call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) on the Item before your first call to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . If you skip calling [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) , the Item's first call to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will take longer and be less accurate, because Signal will not have had the opportunity to pre-load certain data about the Item. Subsequent calls to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) on the Item will have higher accuracy.

---


# Signal - Introduction to Plaid Signal | Plaid Docs

Introduction to Plaid Signal  
==============================

#### Evaluate ACH payment risk 

Get started with Plaid Signal

[API Reference](https://plaid.com/docs/api/products/signal/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/6786ccc5a048a5f1cf748cb5?zoom=100)

#### Overview 

Plaid Signal evaluates the likelihood of a specific transaction resulting in an ACH return. Signal is powered by a machine learning model and data relating to the consumer's linked bank account, and is designed to provide a result in under one second. Signal simplifies payment risk management by:

*   Evaluating payments through [Signal Rules](https://dashboard.plaid.com/signal/risk-profiles) , a no-code dashboard that allows you to react quickly to changing trends
    
*   Suggesting custom rules based on your payments and returns activity, allowing you to easily set thresholds for accepting payments
    
*   Providing over 80 predictive insights that you can incorporate into your own risk assessment models
    

Signal considers over 1,000 risk factors to evaluate proposed transactions. Over time, as you use it, it will provide more customized and refined recommendations.

Plaid Signal can evaluate the risk of US domestic transactions over ACH (both Standard and Same Day ACH). Signal cannot be used to evaluate RTP or RfP transactions, debit card transactions, transactions to or from a non-US bank account, or wire transfers. For these use cases, use [Balance](https://plaid.com/docs/balance/index.html.md) instead. For more details, see [Signal vs. Balance comparison chart](https://plaid.com/docs/payments/index.html.md#balance-and-signal-comparison) .

#### How Signal works 

Plaid Signal works in two steps:

First, it analyzes and summarizes the level of risk a transaction poses into a [risk score](https://plaid.com/docs/signal/index.html.md#signal-transaction-risk-scores) .

Second, it uses [rulesets](https://plaid.com/docs/signal/index.html.md#signal-rulesets) to turn these scores into actions. You must create and tune these rulesets to match your business's risk tolerance.

##### Signal transaction risk scores 

When you call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , Signal will generate a risk score for a proposed transaction, predicting the likelihood of returns due to insufficient funds, closed or frozen accounts, and other administrative bank returns, as well as consumer authorized returns. A higher risk score indicates a greater likelihood that the transaction will result in an ACH return.

##### Signal rulesets 

To turn these risk scores into an action, you will configure a [Signal Ruleset](https://plaid.com/docs/signal/signal-rules/index.html.md) . Signal can suggest an initial set of rules to approve payments below a certain risk score threshold. Signal provides you with access to both the aggregate score and over 60 predictive insights, allowing you to set up simple score-based rulesets or to create more complex rules.

(An image of "Image of example distribution of Plaid Signal scores")

The shape of this graph (how many transactions are low risk versus high risk) is unique per customer. [Reporting returns](https://plaid.com/docs/signal/reporting-returns/index.html.md) will allow the Signal Dashboard to provide you with personalized recommendations for [adjusting score thresholds](https://plaid.com/docs/signal/signal-rules/index.html.md) .

It is recommended that you roll out Signal in stages to collect data, then use the Dashboard tools to adjust your approval logic at each rollout phase.

#### Integration overview 

1.  [Create a new Item with Signal](https://plaid.com/docs/signal/creating-signal-items/index.html.md) or [add Signal to an existing Item](https://plaid.com/docs/signal/creating-signal-items/index.html.md#adding-signal-to-existing-items) .
    
2.  [Create a Signal ruleset](https://plaid.com/docs/signal/signal-rules/index.html.md) using the Dashboard.
    
3.  [Call /signal/evaluate and determine the next steps based on results](https://plaid.com/docs/signal/signal-rules/index.html.md#using-signal-rule-results) .
    
4.  [Report ACH returns and decisions](https://plaid.com/docs/signal/reporting-returns/index.html.md) to Signal.
    
5.  After launch, periodically review and [tune your Signal Rules](https://plaid.com/docs/signal/tuning-rules/index.html.md) using the Dashboard.
    

#### Billing 

Signal is billed on a per-request fee basis based on the number of calls to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . For more details, see [per-request flat fee billing](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) .

---


# Signal - Reporting returns | Plaid Docs

Reporting returns and decisions 
================================

#### Improve accuracy by reporting outcomes 

It's critical that you report ACH activity (both decisions and returns) back to Plaid - reporting enables Plaid to help you tune your rule logic to optimize your integration.

For both decisions and returns, you can use API endpoints (recommended) or upload the transactions manually via the Signal Dashboard.

#### Reporting decisions 

Reporting a decision allows Plaid to know that the transaction was processed. Once it knows the transaction was processed, if Signal doesn't hear about a corresponding return, it assumes the transaction was successful.

Plaid will automatically infer decisions for customers using Signal Rules with only `ACCEPT` or `REROUTE` results. There is no need to report decisions back to Plaid for these transactions unless the decision has changed (for example, your processor refused to process an `ACCEPT`ed transaction).

If your rules integration uses `REVIEW` results, then you'll need to call [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) once you've made the final determination for the transaction and it is convenient to do so.

If your integration is directly reading scores and attributes instead of using Signal Rules, then you'll need to call [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) for all transactions.

#### Reporting returns 

To report an ACH return to Plaid, call [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) as soon as you're aware of the ACH return and it's convenient to do so.

#### Dashboard upload 

If you would prefer to not report decisions and returns via API, you can upload them via the [data import](https://dashboard.plaid.com/signal/import) page in the Dashboard. It is recommended you upload reports on a weekly basis.

The CSV files for uploading decisions and returns must follow the schemas defined below. Ensure your data is properly formatted to avoid processing errors.

##### Decision File CSV Schema 

| Column Name | Required? | Data Type | Description |
| --- | --- | --- | --- |
| `client_transaction_id` | Yes | String | Unique identifier for the transaction used in [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) |
| `initiated` | Yes | Boolean | Whether the transaction was initiated for processing or not. |
| `days_funds_on_hold` | No | Integer | Number of days the funds were held before being released, if applicable to your usecase. |
| `amount_instantly_available` | No | Integer | The amount made available instantly in cents, if relevant for your account funding usecase |

[Example decision file CSV](https://plaid.com/documents/signal-decision-import-example.csv)

##### Return File CSV Schema 

| Column Name | Required? | Data Type | Description |
| --- | --- | --- | --- |
| `client_transaction_id` | Yes | String | Unique identifier for the transaction used in [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) |
| `return_code` | Yes | String | The ACH return code (e.g., R01, R02, R10) |
| `returned_at` | No | String | Timestamp of when the return occurred in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZD) |

[Example return file CSV](https://plaid.com/documents/signal-return-import-example.csv)

---


# Signal - Signal Rules | Plaid Docs

Signal Rules 
=============

#### Learn about configuring Signal Rules 

#### Using Signal Rules 

With Signal Rules, you can configure your decision logic directly within the Signal Dashboard using templates from Plaid, then use Dashboard tools to tailor the rules to your own traffic.

Signal Rules can be based on scores (higher scores indicate higher risk), attributes of the transaction, or a combination.

You can set up the following actions for your business to take as a result of a rule:

*   `ACCEPT` and process the transaction
    
*   `REVIEW` the transaction further before processing
    
*   `REROUTE` the customer to another payment method, as the transaction is too risky
    

You can also create more complex action flows through the use of [custom action keys](https://plaid.com/docs/signal/signal-rules/index.html.md#using-a-custom-action-key-for-advanced-actions)

You can define a single ruleset for all your transactions, or you can build use-case specific rulesets, such as one for an initial deposit during customer onboarding and another for a returning customer depositing funds.

#### Creating a ruleset 

Create rulesets on the [Signal Rules Dashboard](https://dashboard.plaid.com/signal/risk-profiles) page. You can create a ruleset from scratch, or Plaid can suggest an initial rule template relevant for your use case by utilizing context collected during your Signal onboarding (such as transaction size).

Rules are evaluated sequentially, from top to bottom, typically ordered by the severity of the rule violation. If data that the rule depends on is not available, the rule will be skipped.

The `result` of the first rule that matches will be applied to the transaction and included in the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response. You will be required to have a fallback rule that is applied if no other rules match.

(An image of "Example Plaid Signal Ruleset")

Signal Ruleset example configuration

#### Using Signal Rule results 

To evaluate a transaction's risk, call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) and include the required request properties in addition to the ruleset's `ruleset_key`, which can be found in the Dashboard, in smaller type under the name of the ruleset.

The more properties you provide when calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , such as the `user` or `device` fields, the more accurate the results will be. Providing the `client_user_id` is also recommended to aid in your debugging process later.

In the response, use the `ruleset.result` property to determine the next steps.

Most integrations use the `result` to decide between approving a payment for processing (`result=APPROVE`), or rerouting the consumer to another payment method (`result=REROUTE`). If that's the case with your integration, ensure that your ruleset emits only these two result types.

If your integration is taking more complex actions before deciding whether to process the transaction (for example, sending certain transactions to a manual review queue), use the `REVIEW` result type. Remember to [report the final decision](https://plaid.com/docs/signal/reporting-returns/index.html.md#reporting-decisions) for these reviewed transactions later.

Signal can never be used as an input to determine a consumer's eligibility to access your services. Signal evaluates the risk of a transaction from a specific bank account and can be used to determine if you should require the user to use a different payment method, according to your risk tolerance.

##### For existing customers prior to May 2025: Migrating away from the outcome field 

Customers who used Signal Rules before May 2025 used the [ruleset.outcome](https://plaid.com/docs/api/products/signal/index.html.md#signal-evaluate-response-ruleset-outcome) field. This field has been replaced by [ruleset.result](https://plaid.com/docs/api/products/signal/index.html.md#signal-evaluate-response-ruleset-result) . Update your integration to use the new values from the `ruleset.result` field:

| Outcome (old) | Result (new) |
| --- | --- |
| `block` | `REROUTE` |
| `accept` | `ACCEPT` |
| `review` | `REVIEW` |

For most integrations, that's all you need to change. Once you've updated your integration, inform your account manager.

If you have an advanced use case where you take different actions for transactions with the same `result`, you can use the `custom_action_key`. For example, to apply a variable hold time, make sure your Signal rules emit an `result=ACCEPT` value for all transactions you intend to process. Then, use the `custom_action_key` to define a `3-day-hold` for some rules and `5-day-hold` for others. For more details, see [Using a custom action key](https://plaid.com/docs/signal/signal-rules/index.html.md#using-a-custom-action-key-for-advanced-actions) .

#### Using a custom action key for advanced actions 

Some integrations may need more options for handling a transaction than the three choices of accept, review, or reroute. For example, you might want to apply a variable hold time to transactions that were accepted and processed, depending on the level of risk. Or you may want to apply labeling to their transactions to denote a cohort for data analysis purposes. To support more complex actions, check the "Configure advanced options" box on the rule editing screen and specify a `custom_action_key`.

You can then create multiple rules with the same result but different custom actions. For example:

*   If medium risk, `ACCEPT` with `custom_action_key=5-day-hold`
    
*   If low risk, `ACCEPT` with `custom_action_key=3-day-hold`
    

When calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , use the [custom\_action\_key](https://plaid.com/docs/api/products/signal/index.html.md#signal-evaluate-response-ruleset-triggered-rule-details-custom-action-key) in the response to determine the action to take.

#### Data availability limitations 

The amount of consumer-permissioned data available to Signal can vary. Signal attempts to prefetch this data at a regular cadence and will also attempt to fetch fresh data during the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) call if needed. Most Signal evaluations will return information about the Item's use in the network, the latest balance, historical balance information, or account activity. The full set of data is usually available to Signal within 15 seconds of Plaid Link being completed. However, partial data may be returned if [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is called before this process completes, the Item has been inactive for a long time, or the financial institution's connectivity to Plaid is degraded or down.

When used with Items that do not have a connection to a financial institution, (i.e., Items created verified using [alternative methods](https://plaid.com/docs/auth/coverage/index.html.md) such as micro-deposits or Database Auth), Signal can generate risk scores for approximately 30% of these Items, although Items created in this way will have no data in the `core_attributes` response property. If Signal can't get data, the `scores` property will be `null`, and any rules using `score` will be skipped (potentially triggering your fallback rule). You will still be billed for the evaluation (unless you have no Signal Ruleset enabled).

#### Testing Signal Rules in Sandbox 

In the Sandbox environment, scores and attributes returned by [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will be randomly generated. You can influence the score returned by [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) in Sandbox by providing particular values in the `amount` request field. Use the values from the following table to control the returned score:

| Amount | Score |
| --- | --- |
| 3.53 | 10 |
| 12.17 | 60 |
| 27.53 | 90 |

You can use these hardcoded responses and create simple rules in Sandbox (such as `REROUTE if bank_score == 90`) to test various result types.

#### Debugging transactions 

All evaluations can be viewed in realtime on the [transactions viewer](https://dashboard.plaid.com/signal/transactions-viewer) Dashboard page. Look up your transaction using its `client_transaction_id`. You can see its scores, the ruleset's `result`, and the data used to build the score.

#### Debugging rules 

You can view all transactions that matched a specific rule by clicking `View Performance` in the `...` icon on the rule.

(An image of "Navigation to the rule performance page")

Navigation to the rule performance page

(An image of "Example performance page for a single Signal rule")

Performance page of a single rule

#### Tuning your rules 

After your integration is live, Signal will report metrics such as approval rate, and ACH return rate, in the Signal Dashboard. You will use these Dashboard tools to [tune your rule logic](https://plaid.com/docs/signal/tuning-rules/index.html.md) , which is a critical step in a successful launch.

You must integrate the [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) endpoint to use the Plaid Dashboard performance data features. If you do not report returns, Plaid will not show Signal performance.

#### Accessing scores and attributes directly via API 

Plaid strongly recommends using Signal Rules. However, if you have your own risk management system in which you are using Signal as one of multiple data sources, you might choose to ingest Signal data directly via the API instead instead. If you don't use Signal Rules, Plaid may be limited in the support it can offer you in tuning external logic.

To directly access Signal's scores and data attributes, call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . The `scores` and `core_attributes` properties in the response will contain the raw Signal data you can provide to your model. For a full listing of `core_attributes`, see the sample response or contact your Account Manager.

Even if you aren't using Signal Rules, it's still recommended to [report decisions and returns](https://plaid.com/docs/signal/reporting-returns/index.html.md) in order to use the [Signal Performance pane](https://plaid.com/docs/signal/signal-rules/index.html.md#tuning-your-rules) , which helps you find the right score threshold.

---


# Signal - Tuning the Signal Rules | Plaid Docs

Tuning your Signal Rules 
=========================

#### Learn about tuning your Signal Rules logic 

#### Overview 

The set of initial rules Plaid suggests when creating a ruleset is meant to be a starting point. Tuning the logic within your [Signal Rules Dashboard](https://dashboard.plaid.com/signal/risk-profiles) is an important step in achieving the right outcomes for your business.

This guide outlines how to incrementally and systematically tune your Signal ruleset to optimize payment acceptances while managing risk. This guide assumes you have integrated using [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) .

##### Step 1: Confirm your ruleset has enough data 

Before you get started adjusting rules, ensure your ACH returns are [reported to Plaid](https://plaid.com/docs/signal/reporting-returns/index.html.md#reporting-returns) . You can tune your rules at any time, but having significant data (i.e. at least hundreds of ACH returns) will be most effective.

##### Step 2: Review performance of current ruleset 

To review an active ruleset’s performance, locate the [ruleset](https://dashboard.plaid.com/signal/risk-profiles) , and click into it. Review the metrics shown for accepted, reviewed, and rerouted transactions, as well as your ACH return rate. Adjust the timeframe in the top right to relevant traffic.

(An image of "Performance page of a ruleset")

Performance page of a ruleset

##### Step 3: Set a tuning objective 

After analyzing the current performance, establish the right goal for your business (usually either reducing returned transactions, or increasing accepted transactions).

For example, do you want to:

*   _Reduce_ ACH return rates?
*   _Increase_ ACH acceptance rates?

As with all risk-based approaches in payments, there is a fundamental tradeoff between the percentage of payments accepted, and the amount of risk taken on in doing so. If you want to increase your acceptance rate, you’ll likely see a higher percentage of returned transactions. If you want to reduce the percentage of returned transactions, this often means lowering your acceptance rate.

##### Step 4: Choose a rule to adjust 

Once you’ve established your goal, it’s time to try editing a rule. We recommend starting by selecting a rule that uses the Bank Score as a parameter and `REROUTE` as the result. By lowering the risk score threshold needed to `REROUTE` the payment, you’ll lower your acceptances, and your ACH return rate. By raising the risk score threshold needed to `REROUTE` the payment, you’ll increase your acceptance rate and your return rate.

You can check which rules are matching the most traffic from the Ruleset rule page. The number of transactions that matched each rule, since the last revision of the ruleset was published, is listed under the ‘Transactions’ column.

(An image of "Ruleset overview page, showing transaction counts")

Ruleset overview page, showing transaction counts

To see the percentage of transactions that currently match a rule, click “edit” on the rule. The right-hand side of the edit screen will show “Matching Transactions.” In the example below, we can see that 1.2% of transactions are deemed as too high risk to proceed, and thus `REROUTE`’d to another payment method.

(An image of "Rule detail page")

Rule detail page

##### Step 5: Tune the rule 

Next, adjust the risk score threshold for the rule. Use the graph icon 📈 beside the rule conditions to understand the distribution of your traffic with a given score.

In this view, we can see estimates on how much traffic is assigned scores near this datapoint. Drag the slider from right to left to see estimates detailing the percentage of traffic that would be `REROUTE`d. In particular, it’s useful to see red transactions in this graph. These are transactions that previously were processed but resulted in an ACH return.

(An image of "Performance page, showing distribution of scores")

Performance page, showing distribution of scores

If you are looking to reduce ACH returns, you should lower the risk score threshold in the REROUTE rule (example: go from 85 -> 80). This will mean _more_ transactions are rerouted. If you are looking to increase acceptances, you should _raise_ the risk score threshold (example: go from 85 to 90).

Once you have found a viable new risk score threshold to use, save it in the rule.

##### Step 6: Save and review adjustment impact 

Once you have found a threshold that looks compelling, “Save” this working edit to return the ruleset overview page. Here, you can get an estimate of the overall impact of all staged edits. Look for projected changes in accepted transactions, and return rate.

(An image of "Ruleset overview page showing backtested results")

Ruleset overview page showing backtested results

For the example rule above, you can see if you publish this change, you will `REROUTE` more transactions to other payment methods, but in return you’ll lower your returns meaningfully. If this is a worthwhile tradeoff for your business, click “Review and publish” to push these edits to your live traffic.

##### Step 7: Publish the rule 

Click “Review and publish” to push edits to live traffic. This will take effect immediately.

(An image of "Dialog that allows you to push the edits live")

Dialog that allows you to push the edits live

##### Step 8: Observe results over time 

Continue monitoring rule performance for return rate and acceptance rate shifts. Plaid recommends visiting the dashboard regularly to measure the effects of published changes to rules. Iterate and adjust your thresholds as needed.

**Note on increasing acceptance rate** - If you are increasing the percentage of accepted transactions, this means you are going to process transactions that would have previously been rerouted to another payment method. Because those prior transactions were not processed, and thus there was no insight on if they resulted in an ACH return, Plaid cannot provide a concrete estimated return rate. For this reason, it’s recommended to increase your acceptance rate slowly over a period of time.

#### Advanced / Larger-scale rule tuning 

Once you’ve observed over 5,000 ACH returns, Plaid can more intelligently analyze your traffic on your behalf, such as finding what additional datapoints may strongly correlate with risk for your particular traffic, and provide updated rules and risk thresholds.

This process is currently in Beta, and is offered with your existing Signal pricing. Please [file a support ticket](https://dashboard.plaid.com/support/new/admin/account-administration) if you have enough traffic, and would like to use it.

---


# Statements - Introduction to Statements | Plaid Docs

Statements 
===========

#### Retrieve a PDF copy of a user's financial statement 

Get started with Statements

[API Reference](https://plaid.com/docs/api/products/statements/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md)

#### Overview 

Statements (US only) allows you to retrieve an exact, bank-branded, PDF copy of an end user's bank statement, directly from their bank. The Statements product simplifies the process of collecting documents for loan verification purposes or rental application review purposes, among others.

[Prefer to learn by watching? Get an overview of how Statements works in just 3 minutes!](https://www.youtube.com/watch?v=DppLEPqU3cs)

#### Integration process 

1.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to create a link token.
    *   Include a statements object containing fields `start_date` and `end_date`. Plaid allows extracting up to 2 years of statements.
    *   If your integration uses multiple Plaid products, such as Assets and Statements, we recommend that you put your other products in the `products` array and put `statements` in the `required_if_supported_products` array. This configuration will require statements to be extracted if the financial institution supports the product, but will not block the user from progressing if statements are not supported. Instead, if Statements is not supported by the user's institution, you will receive a [PRODUCTS\_NOT\_SUPPORTED](https://plaid.com/docs/errors/item/index.html.md#products_not_supported) error when calling Statements endpoints. For more details, see [Choosing how to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) .
    *   If you are using only the Statements product, put statements in the products array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

```javascript
const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}
```

1.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
    
2.  Once the user has successfully finished the Link session, the client-side `onSuccess` callback will fire. Extract the `public_token` from the callback and exchange it for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .
    
3.  Call [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) , passing the `access_token` obtained above. This will return a list of statements, including a `statement_id` for each.
    
    ```json
    {
          "accounts": [
            {
               "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
               "account_name": "Plaid Checking",
               "account_type": "depository",
               "statements": [
                  {
                    "month": 1,
                    "statement_id": "efgh12e3-gh1c-56d6-e7e9-923bc64d80a5",
                    "year": 2024
                  },
                  {
                    "month": 2,
                    "statement_id": "jklh12e3-ab3e-87y3-f8a0-908bc64d80a5",
                    "year": 2024
                  }
                  {
                    "month": 3,
                    "statement_id": "4710abc-af28-481a-991a-48387a7345ddf",
                    "year": 2024
                  }
               ]
            }
          ],
          "institution_id": "ins_118923",
          "institution_name":  "First Platypus Bank",
          "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
          "request_id": "NBZaq"
       }
    ```
    
4.  Call [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) , passing in the `access_token` and desired `statement_id`, to download a specific statement. The statement will be provided in PDF format, exactly as provided by the financial institution.
    
    (An image of "Mock bank statement from First Platypus Bank with account summary and February 2022 transactions. Retrieved via /statements/download.")
    
    Sample Sandbox (mock) bank statement retrieved with /statements/download.
    
5.  (Optional) If you would like to re-check for new statements generated after the end user linked their account, you can call [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) . When the [STATEMENTS\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/statements/index.html.md#statements_refresh_complete) webhook has been received, call [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) again for an updated list of statements.
    

#### Adding Statements to an existing Item 

If your user has already connected their account to your application for a different product, you can add Statements to the existing Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md) .

To do so, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request described in the [Integration process](https://plaid.com/docs/statements/index.html.md#integration-process) , populate the `access_token` field with the access token for the Item, and set the `products` array to `["statements"]`. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Statements consent step. Otherwise, they will be prompted to complete the full Link flow.

#### Supported accounts and institutions 

Statements currently supports only bank depository accounts (e.g. checking and savings accounts).

Statements support includes the following major institutions:

*   Bank of America
*   Chase (Early Availability; contact your Plaid Account Manager to request access)
*   Citibank
*   Fifth Third Bank
*   Huntington Bank
*   Navy FCU
*   Regions Bank
*   TD Bank
*   Truist
*   US Bank
*   Wells Fargo

In addition to the institutions named above, Statements also supports several smaller banks and credit unions. Statements does not currently support all major or long tail-institutions, and should be used with a fallback option in case data is not available.

#### Testing Statements 

Statements can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) , where a mock statement is returned. In Production, the statement is retrieved from the financial institution. Existing customers whose Plaid teams were created in 2023 or earlier may need to file a [product access request](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) to access Statements in the Sandbox.

#### Statements user experience 

(An image of "Plaid screens showing bank connection, bank selection, credential entry, account selection, and access request for sharing statements.")

The end user experience for sharing bank statements.

#### Statements pricing 

Statements is billed when [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is successfully called for Statements, with the cost based on the number of statements between the provided start and end dates, according to a [flexible per-Item fee model](https://plaid.com/docs/account/billing/index.html.md#per-item-flexible-fee) . Statements Refresh is billed based on the number of statements extracted between the provided start and end dates when calling [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) , based on a [flexible per-request fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flexible-fee) . To view the exact pricing you may be eligible for, [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Support - Overview | Plaid Docs

Plaid help and support 
=======================

#### Get help for your Plaid integration 

\=\*=\*=\*=

#### Developer support 

If you are a developer building with Plaid, the answers to most questions can be found in the docs -- try using the search feature, or try ["Ask Bill" within the search menu](https://plaid.com/docs/support/?showChat=true/index.html.md) to ask our friendly chatbot for help!

Troubleshooting details for specific errors or failed requests can be found in the Dashboard:

*   The [Institution status page](https://dashboard.plaid.com/activity/status) provides details on institution support, downtime, and connectivity.
*   The [logs page](https://dashboard.plaid.com/developers/logs) provides details on specific requests.
*   The [Item Debugger](https://dashboard.plaid.com/activity/debugger) provides details on specific Items or Link sessions.

If you do not have a Dashboard account, you can ask the team member who manages your Plaid team to [invite you](https://plaid.com/docs/account/teams/index.html.md#managing-team-member-permissions) to the team.

For general questions about using Plaid APIs or your integration you can also ask the [Plaid community on Stack Overflow](https://stackoverflow.com/questions/tagged/plaid) or [Discord](https://discord.gg/sf57M8DW3y) .

If you can't find an answer to your question, [file a Support ticket](https://dashboard.plaid.com/support) via your Dashboard account. To file a support ticket, you must have Production access; if you do not already have it, complete the [Production request flow](https://dashboard.plaid.com/overview/production) . You will also need the [Support permission](https://plaid.com/docs/account/teams/index.html.md#managing-team-member-permissions) on your team; if you don't have it, contact your team administrator for help.

\=\*=\*=\*=

#### No code support 

If you're looking for a third party who can build a Plaid integration for you, rather than building one yourself, see [integration support](https://plaid.com/docs/resources/index.html.md#integration-support) .

\=\*=\*=\*=

#### Prospective customer support 

If you have a question about Plaid capabilities that isn't answered in the docs, or for details about pricing, [contact Sales](https://plaid.com/contact/) to learn more.

\=\*=\*=\*=

#### Consumer support 

If you are using Plaid to connect your financial accounts and have questions, use the links below for more information:

To learn more about Plaid and how it works, see our page on [How Plaid Works](https://plaid.com/how-it-works-for-consumers/) .

If you are having trouble linking your financial institution, see our [Connecting Financial Accounts](https://support-my.plaid.com/hc/en-us/categories/4405983222679-Connecting-Financial-Accounts) Guide on the [Plaid Help Center](https://support-my.plaid.com/hc/en-us) for more information. If you have questions about linking through a specific Plaid-powered app, we recommend reaching out to the app directly for assistance.

##### Managing or disconnecting your Plaid linked bank accounts 

Manage Plaid's access to your financial data via the [Plaid Portal](https://my.plaid.com/) at [https://my.plaid.com/](https://my.plaid.com/) . You can use the portal to review your current connections, disconnect financial accounts from an app, or delete your data from Plaid's systems.

##### Privacy and security information for consumers 

For more information on Plaid's privacy and security practices, see [How we handle data](https://plaid.com/how-we-handle-data/) .

\=\*=\*=\*=

#### Core Exchange and Plaid Exchange documentation and support 

If you are a developer at a bank or other financial institution looking for information about APIs used to provide consumer-permissioned data to Plaid, help and documentation for the Core Exchange and Plaid Exchange APIs can be found on their dedicated sites:

*   [Core Exchange API documentation](https://plaid.com/core-exchange/docs)
*   [Plaid Exchange API documentation](https://plaid.comhttps://plaid.com/exchange/docs/index.html.md)

---


# Transactions - Add Transactions to your app | Plaid Docs

Add Transactions to your app 
=============================

#### Learn how to fetch Transactions data for your users 

Try out the [Pattern Demo](https://pattern.plaid.com) for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case.

In this guide, we'll start from scratch and walk through how to use Transactions to perform an initial fetch of a user's transaction history. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Fetching transaction data](https://plaid.com/docs/transactions/add-to-app/index.html.md#fetching-transaction-data) .

For a detailed, step-by-step view, you can also watch our full-length, comprehensive tutorial walkthrough on integrating transactions.

[Watch video](https://www.youtube.com/watch?v=Pin0-ceDKcI)

#### Get Plaid API keys and complete application and company profile 

If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.

#### Install and initialize Plaid libraries 

You can use our official server-side client libraries to connect to the Plaid API from your application:

```javascript
// Install via npm
npm install --save plaid
```

After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.

```javascript
// Using Express
const express = require('express');
const app = express();
app.use(express.json());


const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');


const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});


const client = new PlaidApi(configuration);
```

#### Create an Item with Link 

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .

Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .

Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.

The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) sample code below will create an Item with a maximum of 90 days of transaction history. To request more, set the `transactions.days_requested` parameter in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request.

##### Create a link\_token 

```javascript
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: ['transactions'],
    language: 'en',
    webhook: 'https://webhook.example.com',
    redirect_uri: 'https://domainname.com/oauth-page.html',
    country_codes: ['US'],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});
```

##### Install Link dependency 

```jsx

  Connect a bank
  

```

##### Configure the client-side Link handler 

```javascript
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token)).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});


linkHandler.open();
```

#### Get a persistent access token 

Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the `access_token` and `item_id` in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

Current librariesLegacy libraries

```javascript
app.post('/api/exchange_public_token', async function (
  request,
  response,
  next,
) {
  const publicToken = request.body.public_token;
  try {
    const response = await client.itemPublicTokenExchange({
      public_token: publicToken,
    });


    // These values should be saved to a persistent database and
    // associated with the currently signed-in user
    const accessToken = response.data.access_token;
    const itemID = response.data.item_id;


    res.json({ public_token_exchange: 'complete' });
  } catch (error) {
    // handle error
  }
});
```

#### Fetching transaction data 

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and fetch transaction data using the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint.

The [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint is used to both initialize your view of transactions data, and keep you current with any changes that have occurred. When you first call it on an Item with no `cursor` parameter, transactions data available at that time is returned. If more updates are available than requested with the `count` parameter (maximum of 500), `has_more` will be set to `true`, indicating the endpoint should be called again, using the `next_cursor` from the previous response in the `cursor` field of the next request, to receive another page of data. After successfully pulling all currently available pages, you can store the cursor for later requests, allowing Plaid to send you new updates from when you last queried the endpoint.

Note that if you encounter an error during pagination, it's important to restart the pagination loop from the beginning. For more details, see the documentation for [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) . For sample code for handling the error, see the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) API reference.

Typically, the first 30 days of transaction history is available to be fetched almost immediately, but full transaction history may take a minute or more to become available. If you get an empty response when calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) shortly after linking an Item, it's likely that the first 30 days of transaction history has not yet been pulled. You will need to call the endpoint when the data is pulled. Similarly, if you only get the first 30 days of transaction history, you will need to wait until it is complete, and call the endpoint again.

To be notified whenever additional data becomes available, see [Transaction webhooks](https://plaid.com/docs/transactions/webhooks/index.html.md) .

```javascript
// Provide a cursor from your database if you've previously
// received one for the Item. Leave null if this is your
// first sync call for this Item. The first request will
// return a cursor.
let cursor = database.getLatestCursorOrNull(itemId);


// New transaction updates since "cursor"
let added: Array = [];
let modified: Array = [];
// Removed transaction ids
let removed: Array = [];
let hasMore = true;


// Iterate through each page of new transaction updates for item
while (hasMore) {
  const request: TransactionsSyncRequest = {
    access_token: accessToken,
    cursor: cursor,
  };
  const response = await client.transactionsSync(request);
  const data = response.data;


  // Add this page of results
  added = added.concat(data.added);
  modified = modified.concat(data.modified);
  removed = removed.concat(data.removed);


  hasMore = data.has_more;


  // Update cursor to the next cursor
  cursor = data.next_cursor;
}


// Persist cursor and updated data
database.applyUpdates(itemId, added, modified, removed, cursor);
```

#### Updating transaction data 

After your initial [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) request, you may want your application to be notified when any transactions are added, removed, or modified in order to immediately fetch them from [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . To learn how, see [Transaction Webhooks](https://plaid.com/docs/transactions/webhooks/index.html.md) .

#### Example code in Plaid Pattern 

For a real-life example of an app that incorporates transactions, see the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app. Pattern is a sample financial management app that fetches transactions data upon receipt of transactions webhooks. Transactions code in Plaid Pattern can be found in [handleTransactionsWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleTransactionsWebhook.js) .

#### Fetching by date 

If you want to fetch transactions data by date range, you can use the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint.

#### Next steps 

If you're ready to launch to Production, see the Launch checklist.

#### Launch checklist 

Recommended steps to take before launching in Production

[Launch](https://plaid.com/docs/launch-checklist/index.html.md)

---


# Transactions - Introduction to Transactions | Plaid Docs

Introduction to Transactions  
==============================

#### Retrieve up to 24 months of transaction data and stay up-to-date with webhooks. 

(An image of "Link an account")

(An image of "Fetch transactions")

(An image of "Show transactions")

Get started with Transactions

[API Reference](https://plaid.com/docs/api/products/transactions/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/67e1889391fb8841d04eb6ba?zoom=100)

#### Overview 

Transactions data can be useful for many different applications, including personal finance management, expense reporting, cash flow modeling, risk analysis, and more. Plaid's Transactions product allows you to access a user's transaction history for `depository` type accounts such as checking and savings accounts, `credit` type accounts such as credit cards, and student loan accounts. For transaction history from investment accounts, use Plaid's [Investments](https://plaid.com/docs/investments/index.html.md) product.

[Watch video](https://www.youtube.com/watch?v=hBiKJ6vTa4g)

Transactions data available via [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) includes transaction date, amount, category, merchant, location, and more. Transaction data is lightly cleaned to populate the `name` field, and more thoroughly processed to populate the `merchant_name` field. For example data, see the [Transactions API reference](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-sync-response-transactions-update-status) .

##### Typical fill rates for selected fields 

Below are typical fill rates for selected fields returned by Transactions. Not all fields are included in the table below.

| Field | Typical fill rate |
| --- | --- |
| Amount | 100% |
| Date | 100% |
| Description | 100% |
| Merchant name | 97%\* |
| Category (`personal_finance_category`) | 95% |

\*Denominator excludes transactions that do not have an associated merchant, such as cash transactions, direct deposits, or bank fees.

#### Integration overview 

The steps below show an overview of how to integrate Transactions. For a detailed, step-by-step view, you can also watch our full-length, comprehensive tutorial walkthrough.

[Watch video](https://www.youtube.com/watch?v=Pin0-ceDKcI)

1.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Along with any other parameters you specify, make sure to include the following:
    
    *   The `products` array should include `transactions`.
    *   Specify a `webhook` receiver endpoint to receive transactions updates.
    *   Specify a value for `transactions.days_requested` corresponding to the amount of transaction history your integration needs. The more transaction history is requested, the longer the historical update poll will take. The default value is 90; the maximum value is 730.
2.  On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
    
3.  Once the end user has completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) .
    
4.  Create a method to call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . This method must do the following:
    
    *   The first time [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is called on an Item, call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) with no cursor value specified
    *   Save the `next_cursor` value returned by [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) to use as an input parameter in the next call to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync)
    *   If `has_more` in the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) response is `true`, handle paginated results by temporarily preserving the current cursor, then calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) with the newly returned cursor. After each [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) call, call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) with the newly returned cursor from the previous [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) call until `has_more` is `false`.
    *   When handling paginated results, if `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION` error is returned during pagination, restart the process in the previous bullet with the old cursor that was temporarily preserved. Once `has_more` is `false`, it is safe to stop preserving the old cursor.
    
    For an example, see [fetchNewSyncData](https://github.com/plaid/tutorial-resources/blob/main/transactions/finished/server/routes/transactions.js#L31) and [syncTransactions](https://github.com/plaid/tutorial-resources/blob/main/transactions/finished/server/routes/transactions.js#L110) .
    
5.  Call the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) wrapper you created in the previous step, passing in the `access_token`, in order to activate the Item for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook. It is common that no transactions will be returned during this first call, as it takes Plaid some time to fetch initial transactions.
    
6.  (Optional) Wait for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook to fire with the `initial_update_complete` field set to `true` and the `historical_update_complete` set to `false`. When this occurs, you may optionally call your [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) wrapper to obtain the most recent 30 days of data. If your end-user is expecting to see data load into your app in real-time, this can help improve the responsiveness of your app.
    
7.  Wait for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook to fire with the `historical_update_complete` field set to `true`. Once it does, call your [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) wrapper to obtain all available updates.
    
8.  From this point forward, Plaid will periodically check for transactions data for your Item. When it detects that new transactions data is available, the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook will fire again. When it does, call your [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) wrapper to receive all updates since the `next_cursor` value. In addition to added transactions, these subsequent updates may also include `removed` or `modified` transactions. For details, see [Transactions updates](https://plaid.com/docs/transactions/index.html.md#transactions-updates) .
    
9.  (Optional) If you would like to check for updates more frequently than Plaid's default schedule, call [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) to force an on-demand update via the optional [Transactions Refresh](https://plaid.com/docs/transactions/index.html.md#transactions-refresh) add-on. If any new transaction data is available, a [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook will fire.
    

#### Transactions updates 

Transactions data is not static. As time passes, your users will make new transactions, and transactions they made in the past will change as they are processed by the financial institution. To learn more about how transactions are processed and can change, see [Transaction states](https://plaid.com/docs/transactions/transactions-data/index.html.md) .

Plaid checks for updated transactions regularly, and uses webhooks to notify you of any changes so you can keep your app up to date. For more detail on how to listen and respond to transaction update webhooks, see [Transaction webhooks](https://plaid.com/docs/transactions/webhooks/index.html.md) .

The frequency of transactions update checks is typically one or more times a day. The exact frequency will depend on the institution. To learn when an Item was last checked for updates, you can view the Item in the [Item Debugger](https://dashboard.plaid.com/activity/debugger) . If you would like to display this information in your app's UI to help users understand the freshness of their data, it can also be retrieved via API, using the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) endpoint.

##### Transactions refresh 

You can also request an update on-demand via the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint, which is available as an add-on for Transactions customers. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/settings/team/products) or contact your Plaid account manager.

#### Recurring transactions 

If your app involves personal financial management functionality, you may want to view a summary of a user's inflows and outflows. The [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint provides a summary of the recurring outflow and inflow streams and includes insights about each recurring stream including the category, merchant, last amount, and more. [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) is available as an add-on for Transactions customers in the US, Canada, and UK. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/settings/team/products) or contact your Plaid account manager.

#### Sample app demo and code 

The [Transactions sample app](https://github.com/plaid/tutorial-resources/tree/main/transactions) is a simple app designed to accompany the [Transactions YouTube tutorial](https://www.youtube.com/watch?v=Pin0-ceDKcI) .

Try out the [Pattern Demo](https://pattern.plaid.com) for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case to calculate and display a customer's net worth and spending habits and allows them to link multiple financial institutions.

For a more robust example of an app that incorporates transactions, along with sample code for transactions reconciliation, see the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app.

#### Testing Transactions in Sandbox 

Plaid provides several special users for testing Transactions. One example is `user_transactions_dynamic` (password: any non-blank password). You can create a public token for this user using [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) ; if using the interactive Link flow, you must use a non-OAuth test institution such as First Platypus Bank (`ins_109508`).

Unlike `user_good`, `user_transactions_dynamic` contains realistic, dynamic transactions data and can be used together with the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint to simulate Transactions updates and trigger webhooks in Sandbox. For more details on how to simulate transaction activity with this user, see [Testing pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#testing-pending-and-posted-transactions) .

If you are using the [Recurring Transactions add-on](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) , you can also use `user_transactions_dynamic` to test recurring transactions in Sandbox. This user has six months of recurring transactions.

To add your own custom transactions to `user_transactions_dynamic`, call [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) . This simulates a [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) call where Plaid will see those custom transactions as new transactions. All corresponding webhooks will fire.

For persona-based testing, Plaid also provides `user_ewa_user`, `user_yuppie`, and `user_small_business` users. These accounts simulate real life personas, so new transactions will appear at a more realistic rate and will not appear every time [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) is called. These users have three months of transactions, including some recurring transactions. These users also require a non-OAuth test institution.

| User Name | Description | Password | Institution | Transaction Data | /transactions/refresh generates new txns | Recurring Txns |
| --- | --- | --- | --- | --- | --- | --- |
| `user_transactions_dynamic` | Dynamic data | Any non-blank | `ins_109508` (First Platypus Bank) | Triggers webhooks and new data consistently, allows adding custom transactions | Always | Yes (6 months) |
| `user_ewa_user` | Earned-wage access persona | Any non-blank | Same as above | 3 months of realistic data | Sometimes | Yes (some) |
| `user_yuppie` | Young affluent professional | Any non-blank | Same as above | 3 months of realistic data | Sometimes | Yes (some) |
| `user_small_business` | Small business persona | Any non-blank | Same as above | 3 months of realistic data | Sometimes | Yes (some) |

#### Transactions pricing 

Transactions and the optional Recurring Transactions add-on are billed on a [subscription model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) . The optional Transactions Refresh add-on is billed on a [per-request model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact Sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

To get started building with Transactions, see [Add Transactions to your App](https://plaid.com/docs/transactions/add-to-app/index.html.md) .

If you're ready to launch to Production, see the Launch Center.

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)

---


# Transactions - Personal Finance Category migration guide | Plaid Docs

Personal Finance Category migration guide 
==========================================

#### Learn how to migrate from Plaid's legacy categories to the new personal finance categories 

#### Overview 

Personal finance categories (PFCs), returned by all Transactions endpoints as of September 2023, provide more meaningful categorization at greater accuracy compared to the legacy category fields. All Transactions implementations are recommended to use PFCs rather than the legacy taxonomy. The PFC taxonomy is composed of fewer, better-defined categories based on customer needs and what users expect to see in a personal finance management app. Although PFCs are most relevant for personal finance use cases, they are not limited to those use cases.

PFCs are composed of the following fields:

*   `personal_finance_category.primary`: A high level category that communicates the broad category of the transaction
*   `personal_finance_category.detailed`: A granular category conveying the transaction's intent; this field can also be used as a unique identifier for the category
*   `personal_finance_category.confidence_level`: A description of how confident we are that the provided categories accurately describe the transaction's intent
*   `personal_finance_category_icon_url`: The URL of an icon associated with the primary personal finance category

See an example of these two types of categorization below:

```json
...
"category": [
  "Shops",
  "Computers and Electronics"
],
"category_id": "19013000",
...
```

```json
...
"personal_finance_category": {
  "primary": "GENERAL_MERCHANDISE",
  "detailed": "GENERAL_MERCHANDISE_ELECTRONICS",
  "confidence_level": "VERY_HIGH"
},
"personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
...
```

See the [taxonomy CSV file](https://plaid.com/documents/transactions-personal-finance-category-taxonomy.csv) for a full list of PFCs.

Plaid has no plans to remove the legacy categories from the API response at this time. However, we are no longer developing improvements to those fields and strongly recommend using PFCs for the most accurate and up-to-date categorization.

Note that PFCs are not present in Assets endpoints.

#### Updating your internal categorization logic 

Some customers maintain logic that translates Plaid's legacy categories into their own internal categories. In order to facilitate the updating of this translation layer, see the [mapping JSON file](https://plaid.com/documents/transactions-personal-finance-category-mapping.json) for a suggested 1-to-many mapping of our most common legacy categories to possible PFCs. Please note that this file is intended for general taxonomy-to-taxonomy mapping, and individual transactions may be assigned a PFC unaligned with its legacy category as we continue to refine the accuracy of our PFC predictions.

#### Backfilling historical transactions with PFCs 

You may already have historical transactions stored with only the legacy category present. If you are interested in backfilling PFCs for those transactions, you can re-fetch those transactions with a populated PFC using the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoints.

---


# Transactions - Transactions Sync migration guide | Plaid Docs

Transactions Sync migration guide 
==================================

#### Learn how to migrate from the /transactions/get endpoint to the /transactions/sync endpoint 

#### Overview 

[/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is a newer endpoint that replaces [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) and provides a simpler and easier model for managing transactions updates. While [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) provides all transactions within a date range, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) instead uses a cursor to provide all new, modified, and removed transactions that occurred since your previous request. With this cursor-based pagination, you do not need to worry about making redundant API calls to avoid missing transactions. Updates returned by [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) can be patched into your database, allowing you to avoid a complex transaction reconciliation process or having to keep track of which updates have already been applied.

This guide outlines how to update your existing [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) integration to use the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint and simplify your Plaid integration.

Looking for an example in code? Check out [Pattern on GitHub](https://github.com/plaid/pattern) for a complete, best-practice implementation of the Transactions Sync API within a sample app.

#### Update your client library 

If you are using client libraries, you may need to update your current library to use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . The following are the minimum Plaid client library versions required to support [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) for each language:

*   Python: 9.4.0
*   Node: 10.4.0
*   Ruby: 15.5.0
*   Java: 11.3.0
*   Go: 3.4.0

Detailed upgrade notes are language-specific may be found in the README and Changelog of the specific library. See the library's repo on the [Plaid GitHub](https://github.com/plaid) for more information.

#### Update callsites and pagination logic 

Replace all instances of [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) with [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) has a slightly different call signature from [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) and does not have the `count` parameter inside the `options` object and uses a `cursor` instead of a `start_date` and `end_date`. Pagination logic is also different and relies on the `has_more` flag instead of the `transactions_count` value. Note that when requesting paginated updates with [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , unlike when using [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , it is important to retrieve all available updates before persisting the transactions updates to your database.

Unlike [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) does not allow specifying a date range within which to retrieve transactions. If your implementation requires getting transactions within a certain date range, implement transaction filtering after calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .

For copy-and-pastable examples of how to call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , including complete pagination logic, see the API reference code samples for [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .

If a call to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) fails when retrieving a paginated update as a result of the `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION` error, the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.

#### Update callsites for Item data 

Unlike [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) does not return an Item object. If your app relies on getting Item data, such as Item health status, use [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) .

#### Update webhook handlers 

When using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , you should not listen for the webhooks `HISTORICAL_UPDATE`, `DEFAULT_UPDATE`, `INITIAL_UPDATE`, or `TRANSACTIONS_REMOVED`. While these webhooks will still be sent in order to maintain backwards compatibility, they are not required for the business logic used by [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) .

Instead, update your webhook handlers to listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook and to call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) when this webhook is received.

#### Update initial call trigger 

Unlike the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) webhooks, the `SYNC_UPDATES_AVAILABLE` webhook will not be fired for an Item unless [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) has been called at least once for that Item. For this reason, you must call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) at least once before any sync webhook is received. After that point, rely on the `SYNC_UPDATES_AVAILABLE` webhook.

Unlike [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) will not return the `PRODUCT_NOT_READY` error if transactions data is not yet ready when [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is first called. Instead, you will receive a response with no transactions and a null cursor. Even if no transactions data is available, this call will still initialize the `SYNC_UPDATES_AVAILABLE` webhook, and it will fire once data becomes available.

The first call to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) once historical updates are available will often have substantially higher latency (up to 8x) than the equivalent call in a [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) \-based implementation. Depending on your application's logic, you may need to adjust user-facing messaging or hard-coded timeout settings.

#### Update transaction reconciliation logic 

The response to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) includes the patches you will need to apply in the `added`, `removed`, and `modified` arrays within its response. You should apply these to your transactions records. Any additional logic required to fetch or reconcile transactions data can be removed.

#### Migrating existing Items 

You likely already have transactions stored for existing Items. If you onboard an existing Item onto [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) with `"cursor": ""` in the request body, the endpoint will return all historical transactions data associated with that Item up until the time of the API call (as "adds"). You may reconcile these with your stored copy of transactions to ensure that it reflects the the Item's true state.

If you have a large number of Items to update, this reconciliation process may be slow and generate excessive system load. One other option for onboarding existing Items onto [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is using `"cursor": "now"` in the request body. The endpoint will return a response containing no transaction updates, but only a cursor that will allow you to retrieve all transactions updates associated with that Item going forward, after the time of the API call. Accordingly, you should ensure that your local copy of transactions for an Item is up-to-date at the time you call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) with `"cursor": "now"` for it, or else any transaction updates that occurred between the time that you last pulled fresh data and the time of your [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) call may be missing.

`"cursor": "now"` will work exactly like a cursor that was found by starting with `"cursor": ""` and paginating through all updates, with the only difference being that a transaction created before, but modified after, those requests would be returned as "added" if using `"cursor": "now"`, and "modified" if using `"cursor": ""`.

If you ever want to completely rebuild your local copy of transactions for an Item previously onboarded with `"cursor": "now"`, you may still do so with `"cursor": ""`.

Note that we strongly recommend that this cursor only be used with Items for which you've already used with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , and not any new Items, which should always be onboarded with `"cursor": ""`.

#### Test your integration 

You can perform basic testing of your integration's business logic in Sandbox, using the [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) endpoint to simulate `SYNC_UPDATES_AVAILABLE`. If this testing succeeds, you should then test your integration with internal test accounts before releasing it to your full userbase.

#### Example code 

For a full working example of a Plaid-powered app using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , see [Plaid Pattern](https://github.com/plaid/pattern/tree/master/server) .

---


# Transactions - Transaction states | Plaid Docs

Transaction states 
===================

#### Learn about the differences between pending and posted transactions 

#### Pending and posted transactions 

There are two types of transactions: pending and posted. A transaction begins its life as a pending transaction, then becomes posted once the funds have actually been transferred. It typically takes about one to five business days for a transaction to move from pending to posted, although it can take up to fourteen days in rare situations.

When a transaction posts, the transition from a pending to posted transaction will be represented through the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint with the pending transaction's id in the `removed` field of the response and the new posted transaction in the `added` section of the response -- note that these aren't guaranteed to be in the same page, but should happen within the same overall update. If Plaid matches the pending transaction to the new posted transaction, the pending transaction's id will be marked in the `pending_transaction_id` of the posted transaction.

Some institutions, such as Capital One and USAA, do not provide pending transaction data. If no pending transaction is provided, or the pending transaction cannot be matched, the `pending_transaction_id` will be `null`.

```json
{
  "added": [
    {
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
      "pending": false,
      "name": "Apple Store",
      "amount": 2307.21
      /* ... */
    }
  ],
  "removed": [
    {
      "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l",
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      
      /* ... */
    }
  ],
  "modified": []
  /* ... */
}
```

The pending and posted versions of a transaction may not necessarily share the same details: their name and amount may change. For example, the pending charge for a meal at a restaurant may not include a tip, but the posted version will include the final amount spent, including the tip. In some cases, a pending transaction may not convert to a posted transaction at all and will simply disappear; this can happen, for example, if the pending transaction was used as an "authorization hold," which is a sort of a deposit for a potential future transaction, frequently used by gas stations, hotels, and rental-car companies. Pending transactions are short-lived and frequently altered or removed by the institution before finally settling as a posted transaction.

Note that while transactions will rarely change once they have posted, a posted transaction cannot necessarily be considered immutable. For example, a refund or a recategorization of a transaction by the institution could cause a previously posted transaction to change. This is why it's important to apply all `modified`, `added`, and `removed` updates surfaced through [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) in order to maintain consistency with the underlying account data.

#### Testing pending and posted transactions 

To test dynamic transactions behavior in Sandbox, use the test user `user_transactions_dynamic` with any non-blank password. You can create a public token for this user using [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) ; if using the interactive Link flow, you must use a non-OAuth test institution such as First Platypus Bank (`ins_109508`). An Item associated with this user will be created with 50 transactions in both the `pending` and `posted` state. You can then simulate Plaid receiving more data for this Item by calling [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) . This will generate new `pending` transactions, all previously `pending` transactions will be moved to `posted`, and the amount of one previous transaction will be incremented by $1.00. All appropriate transaction webhooks will also be fired at this time.

Remember that in Production, you don't need to call [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) unless you want to force Plaid to update its transaction data outside of its usual schedule.

#### Example code in Plaid Pattern 

For a real-life example, see [update\_transactions.js](https://github.com/plaid/pattern/blob/master/server/update_transactions.js) . This file demonstrates code for handling transaction states in the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app.

#### Transaction state changes with /transactions/get 

The content in this section and below applies only to existing integrations using the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint. It is recommended that any new integrations use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) instead of [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , for easier and simpler handling of Transaction state changes.

**Reconciling transactions**

[/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) returns both pending and posted transactions; however, some institutions do not provide pending transaction data and will only supply posted transactions. The `pending` boolean field in the transaction indicates whether the transaction is pending or posted.

Plaid does not model the transition of a pending to posted transaction as a state change for an existing transaction; instead, the posted transaction is a new transaction with a `pending_transaction_id` field that matches it to a corresponding pending transaction. When a pending transaction is converted to a posted transaction, Plaid removes the pending transaction, sends a [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) webhook, and returns the new, posted transaction. The posted transaction will have a `pending_transaction_id` field whose value is the `transaction_id` of the now-removed pending transaction. The posted transaction’s date will reflect the date the transaction was posted, which may differ from the date on which the transaction actually occurred.

In some rare cases, Plaid will fail to match a posted transaction to its pending counterpart. On such occasions, the posted transaction will be returned without a `pending_transaction_id` field, and its pending transaction is removed.

**Handling pending and posted transactions**

To manage the movement of a transaction from pending to posted state, you will need to handle the `TRANSACTIONS_REMOVED` webhook to identify the removed transactions, then delete them from your records. For detailed instructions, see [Transactions webhooks](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) .

---


# Transactions - Troubleshooting | Plaid Docs

Troubleshooting Transactions 
=============================

#### API error responses 

If the problem you're encountering involves an API error message, see [Errors](https://plaid.com/docs/errors/index.html.md) for troubleshooting suggestions.

#### No transactions or cursor returned 

When calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , a response with no cursor or transactions data is returned.

##### Common causes 

*   This is expected behavior when the Item has recently been initialized with `transactions` and Plaid has not yet completed fetching of transactions data.

##### Troubleshooting steps 

#### Missing transactions 

##### Common causes 

*   The institution is experiencing an error.
    
*   Processing of the transactions has been delayed.
    
*   The Item is not in a healthy state.
    
*   The transaction is not available on the institution's online banking portal, or appears differently on the online banking portal.
    

##### Troubleshooting steps 

If the steps above do not resolve the issue, [file a ticket with Plaid support](https://dashboard.plaid.com/support/new/financial-institutions/missing-data/missing-transactions) .

#### Incorrect data fields 

In some cases, information about a merchant, such as its name or category, may be incorrect.

##### Troubleshooting steps 

If the issue is not resolved, or if the category information is incorrect, [file a ticket with Plaid support](https://dashboard.plaid.com/support/new/financial-institutions/faulty-data/faulty-transaction-data) indicating which fields are incorrect, the correct data, and the `transaction_id` of the affected transaction.

#### Limited transaction history is returned 

##### Common causes 

*   By default, Plaid will only return 90 days of transaction history. To request more transaction history, specify the `days_requested` field when initializing with Transactions. Note that this field will only take effect when Transactions is added to an Item for the first time; if you need more than 90 days of transactions history for an Item that has already been initialized with Transactions for 90 days of history, you will need to delete the Item and create a new one.
    
*   The user's institution may provide limited transaction history. For example, Capital One provides only 90 days of transaction history and does not provide pending transactions.
    

##### Troubleshooting steps 

*   Specify `days_requested` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or (if not initializing with Transactions during Link) when calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) or [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) for the first time on an Item.
    
*   Verify that the issue is not specific to a particular institution. For details of history available at certain major institutions, see the [Plaid guide to institution-specific OAuth experiences](https://plaid.com/documents/oauth-institution-ux.pdf) .
    

#### Duplicate transactions are returned 

##### Common causes 

*   An end user linked the same bank account to your app multiple times, causing the same transaction data to appear across multiple Items.
    
*   The duplicate transaction data may be an accurate reflection of the end user's transaction activity (e.g. if the end user was double-charged).
    
*   If a transaction is updated, modified, or posted, it will appear as a separate transaction in transaction history. This is expected behavior and your app should have logic to reconcile the two versions of the transaction. For more details, see [Transactions states](https://plaid.com/docs/transactions/transactions-data/index.html.md) .
    
*   There may be an error with the data provided by the institution to Plaid or with Plaid's processing of this data.
    

##### Troubleshooting steps 

If the issue is not resolved, [file a ticket with Plaid support](https://dashboard.plaid.com/support/new/financial-institutions/faulty-data/faulty-transaction-data) indicating which transactions are duplicated, and the `transaction_id`s of the affected transaction.

---


# Transactions - Transactions webhooks | Plaid Docs

Transactions webhooks 
======================

#### Listen for Transaction webhooks to learn when transactions are ready for retrieval or when transactions have been updated. 

#### Introduction 

Webhooks are a useful part of the Transactions product that notifies you when Plaid has new or updated transaction information. This guide will explain how to use webhooks to make sure you have up-to-date transaction history.

#### Configuring Link for transactions webhooks 

Before you can listen to webhooks, you must first set up an endpoint and tell Plaid where to find it. To tell Plaid where to send its webhooks, send your webhook endpoint URL as an optional argument via the `webhook` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) .

You must also initialize your Item with Transactions by including `transactions` in the `products` array provided to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . If you do not do this, Plaid will not attempt to retrieve any transactions for your Item until after [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) or [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) is called for the first time. For more information, see [Choosing how to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) .

#### Integrating the update notification webhook 

After [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is called for the first time on an Item, [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhooks will begin to be sent to the configured destination endpoint.

This webhook will fire whenever any change has happened to the Item's transactions. The changes can then be retrieved by calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) with the `cursor` from your last sync call to this Item.

If at least 30 days of history is available with an update, the `initial_update_complete` parameter in the body of the `SYNC_UPDATES_AVAILABLE` webhook will be `true`. Similarly, `historical_update_complete` will be `true` if the full history (up to 24 months) is available.

For a real-life example that illustrates how to handle this webhook, see [handleTransactionsWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleTransactionsWebhook.js) , which contains the webhook handling code for the Node-based [Plaid Pattern](https://github.com/plaid/pattern) app.

#### Forcing transactions refresh 

Sometimes, checking for transactions a few times a day is not good enough. For example, you might want to build a refresh button in your app that allows your user to check for updated transactions on-demand. To accomplish this, you can use the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) product. After a successful call to [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , if there are new updates, `SYNC_UPDATES_AVAILABLE` will be fired (along with `DEFAULT_UPDATE` and, if applicable, `TRANSACTIONS_REMOVED`).

#### Instructions for integrations using /transactions/get 

The content in this section and below applies only to existing integrations using the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint. It is recommended that any new integrations use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) instead of [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , for easier and simpler handling of transaction state changes. For information on migrating an existing [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) integration to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , see the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) .

When you first connect an Item in Link, transactions data will not immediately be available. [INITIAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#initial_update) and [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) are both webhooks that fire shortly after an Item has been initially linked and initialized with the Transactions product. These webhooks will let you know when your transactions are ready. `INITIAL_UPDATE` fires first, after Plaid has successfully pulled 30 days of transactions for an Item. The `HISTORICAL_UPDATE` webhook fires next, once all historical transactions data is available. `INITIAL_UPDATE` typically fires within 10 seconds, and `HISTORICAL_UPDATE` within 1 minute, although these webhooks may take 2 minutes or more. The time required for the webhooks to fire will depend on the institution, as well as on the number of transactions being processed.

If you attempt to call [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) before `INITIAL_UPDATE` has fired, you will get a [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error. If you attempt to call [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) after `INITIAL_UPDATE` has fired, but before `HISTORICAL_UPDATE` has fired, you will only be able to receive the last 30 days of transaction data. If you did not initialize the Item with Transactions, your first call to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) will result in a `PRODUCT_NOT_READY` error and kick off the process of readying transactions. You can then listen for the `INITIAL_UPDATE` or `HISTORICAL_UPDATE` webhooks to begin receiving transactions.

**Updating transactions**

Plaid fires two types of webhooks that provide information about changes to transaction data: [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) and [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) .

**Adding new transactions**

The [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) webhook fires when new transactions are available. Typically, Plaid will check for transactions at a frequency ranging from one to four times per day, depending on factors such as the institution and account type. If new transactions are available, the `DEFAULT_UPDATE` webhook will fire.

To reflect up-to-date transactions for a user in your app, handle the `DEFAULT_UPDATE` webhook by fetching more transactions. We recommend fetching about 7-14 days of transactions in response to `DEFAULT_UPDATE`. This is typically enough history to ensure that you haven't missed any transactions, but not so much that performance or rate limiting is likely to be a problem.

Once you've fetched these transactions, you will need to identify which transactions are new and which are duplicates of existing data that you have. You should not rely on the number in the webhook's `new_transactions` field to identify duplicates, since it can be unreliable. For example, new transactions may arrive between your receipt of the webhook and your call to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . Instead, compare the `transaction_id` field of each newly fetched transaction to the `transaction_id` fields of your existing transactions, and skip the ones that you already have. For an example, see [Plaid Pattern](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleTransactionsWebhook.js#L176) .

**Removing stale transactions**

The [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) webhook fires when transactions have been removed. The most common reason for this is in the case of pending transactions. In general, transactions start out as pending transactions and then move to the posted state one to two business days later. When Plaid detects that a transaction has moved from pending to posted state, the pending transaction as returned by [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) is not modified. Instead, the pending transaction is removed, and a new transaction is added, representing the posted transaction. For a detailed explanation of pending and posted transactions and how they are handled by Plaid, see [Transaction states](https://plaid.com/docs/transactions/transactions-data/index.html.md) .

Pending transactions can also be removed when they are canceled by the bank or payment processor. A transaction may be removed if its details are changed by the bank so extensively that Plaid can no longer recognize the new and old versions of the transaction as being the same (e.g., a transaction amount and description both being changed simultaneously). In this case, the old transaction will be deleted and a new transaction with the new details will be added. This "transaction churn" can affect both pending and posted transactions.

The `TRANSACTIONS_REMOVED` webhook contains the transaction IDs of the removed transactions, which you can use to identify and remove the corresponding transactions in your own application to avoid presenting duplicated or inaccurate data. If you encounter any problems with the webhook, you can also manually query transaction history for deleted transactions using logic similar to that recommended for handling the `DEFAULT_UPDATE` webhook.

---


# Transfer - Transfer Application | Plaid Docs

Transfer Application 
=====================

#### Get approved to create transfers 

[Request Access](https://dashboard.plaid.com/overview/production) [Create Transfers](https://plaid.com/docs/transfer/creating-transfers/index.html.md)

When you [request access to Transfer in Production](https://dashboard.plaid.com/overview/request-products) , Plaid will collect information from you regarding your business and customer verification processes. If your company is privately held, you will also need to submit identity verification details for a "control person" (such as an executive or senior manager).

#### Originators vs Platforms 

As part of your application, Plaid will confirm what type of Transfer customer you are - either an Originator or a Platform.

(An image of "Image showing two types of transfer customers. Originators move money directly to customers. Platforms involve an intermediary business.")

Types of Transfer customers

Platform Payments is still in beta. If you are interested in Platform Payments, [contact sales](https://plaid.com/contact/) or your Plaid account manager, or see the [Platform Payments documentation](https://plaid.com/docs/transfer/platform-payments/index.html.md) to learn more.

##### What is an originator? 

An Originator initiates ACH payments and is the main beneficiary of these funds. Originators are a party to every transfer and have a direct contractual relationship with the consumer. If you are not contractually obligated to be the main beneficiary of the funds, you are likely a [Platform](https://plaid.com/docs/transfer/application/index.html.md#what-is-a-platform) .

###### Examples of Originators: 

*   Neobank funding a new user account
*   E-commerce website offering ACH as a payment method
*   Lender disbursing loan funds to a user

##### What is a Platform? 

A Platform onboards originators of their own and facilitates money movement between them and their consumers. Platforms do not have a direct contractual relationship with their originator's consumers and are not obligated to be paid; they are simply an intermediary.

###### Examples of Platforms: 

*   Marketplace website that brings buyers and sellers together
*   Any reseller partner, such as a payment processor that provides an SDK to their customers using Plaid transfer functionality
*   SaaS provider that sells account funding tools or payment services
*   Crowdfunding website for nonprofit organizations

To learn more about Plaid's Platform Payments solution, see the [Platform Payments documentation](https://plaid.com/docs/transfer/platform-payments/index.html.md) .

#### Prohibited industries 

There are certain types of businesses, products and industries that can't use Plaid's Transfer services. You must not use Plaid's Transfer services for any illegal activities or for the businesses, product types, or industries listed below. The types of industries listed here are representative of prohibited categories, but this is not an exhaustive list.

*   Adult content or services
*   Marijuana dispensaries and related products
*   Payday lending
*   Weapons or munitions

To use Plaid's Transfer services, you must remain compliant with these industry limitations. There are additional restricted industries that are subject to enhanced due diligence for approval for Transfer usage.

If you have questions about prohibited or restricted industries for Transfer, please [contact us](https://plaid.com/contact/) .

#### Application process 

Requesting access to Transfer involves completing the following forms:

*   The [Production Request form](https://dashboard.plaid.com/onboarding/) (if you already have Plaid Production access for another product, request Transfer via the [Products page](https://dashboard.plaid.com/settings/team/products) instead)
*   The [Transfer Application](https://dashboard.plaid.com/transfer/questionnaire) , also referred to as the Transfer Questionnaire.
*   [Transfer Document collection](https://dashboard.plaid.com/transfer/documents) .

The Transfer Application and Transfer Document Collection cannot be started until the Production Request form is complete. However, you can begin these forms while your Production Request is in review.

If any of these forms are started but not complete, a link to complete them will appear on the main homepage of your Dashboard. You can also access them directly by clicking the links above.

If you don't have all the required information available, you can save any of these forms and complete them later. You can also send links to these forms with other members of your Plaid team to complete. The status of the forms will be shared across the team, so that multiple different team members can each fill out different parts.

##### General information 

*   Description of business
*   Industry
*   General use case(s) (dropdown selection)
*   Business entity and individual information
*   Requested Plaid products

##### Transfer-specific information 

*   Specific description of Transfer use case
*   ACH processing history
*   ACH processing projections

If Plaid is unable to validate individual or entity information through primary methods, we may request supplemental documents. Requests may include documentation to verify:

*   Name (Business entity or individual)
*   Address (Business entity or individual)
*   SSN / EIN
*   DOB

Certain restricted industries will require Enhanced Due Diligence (EDD) specific to that industry. Materials requested during EDD may include:

*   Proof of relevant licensing or registration for regulated activities
*   Copies of policies and procedures related to compliance with regulatory requirements
*   Regulatory audit records
*   Consumer complaint policies
*   Financial statements
*   Terms and conditions
*   Responses to industry-specific questions

Depending on the industry, these materials may be requested either as part of the Transfer application, or later, during the application review process.

#### Implementation checklist 

After your Transfer access has been approved, additional operational tasks required for implementation can be found under [“Transfer > Tasks”](https://dashboard.plaid.com/transfer/implementation-checklist) in the left-hand menu of the Dashboard.

For additional tasks required as part of implementation, see the [Launch Center](https://dashboard.plaid.com/developers/launch-center) .

#### Transfer billing 

Transfer is typically billed as a fee for each transfer, plus a flat fee for each Transfer Item and for each call to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . For details of the transfer pricing model, see the [Transfer billing documentation](https://plaid.com/docs/account/billing/index.html.md#transfer-fee-model) . Exact transfer pricing will vary depending on the details of your business, payments activity, and Plaid integration. After you have completed the Transfer Application form, Plaid will contact you with more information about the pricing that applies to you.

Transfer is available only via a Custom plan with a 12-month minimum contract and is not available via Pay-as-you-go.

---


# Transfer - Creating transfers | Plaid Docs

Linking accounts and creating transfers 
========================================

#### Link accounts and initiate transfers 

Get started with Creating Transfers

[API Reference](https://plaid.com/docs/api/products/transfer/index.html.md)

[Don't feel like reading? Check out this video walkthrough of a working Plaid Transfer application!](https://www.youtube.com/watch?v=A080EKpXbBQ)

#### Account Linking 

Before initiating a transfer through Plaid, your end users need to link a bank account to your app using [Link](https://plaid.com/docs/link/index.html.md) , Plaid's client-side widget. Link will connect the user's account and obtain and verify the account and routing number required to initiate a transfer. Supported account types are debitable checking, savings, or money-market accounts.

See the [Link documentation](https://plaid.com/docs/link/index.html.md) for more details on setting up a Plaid Link session. At a high level, the steps are:

1.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , specifying `transfer` in the `products` parameter.
    
2.  Initialize a Link instance using the `link_token` created in the previous step. For more details for your specific platform, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . The user will now go through the Link flow.
    
3.  The `onSuccess` callback will indicate the user has completed the Link flow. Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` returned by `onSuccess` for an `access_token`. You will also need to obtain and store the `account_id` of the account you wish to transfer funds to or from; this can also be obtained from the `metadata.accounts` field in the `onSuccess` callback, or by calling [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) . You will use the `account_id` later, when [authorizing the transfer](https://plaid.com/docs/transfer/creating-transfers/index.html.md#authorizing-a-transfer) , to specify which account to credit or debit.
    

Once a Plaid Item is created through Link, you can then immediately process a transfer utilizing that account or initiate the transfer at a later time.

The `metadata.accounts.mask` field and the [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint will contain an account mask, typically the last 2-4 digits of the user's account number. When showing the linked account to your end user in your UI, you should always identify it using the mask rather than displaying or truncating the account number, as some institutions provide special account numbers that do not match what the end user is familiar with.

Most major financial institutions require OAuth connections. Make sure to complete the OAuth security questionnaire at least six weeks ahead of time to ensure your connections are enabled by launch. For more information, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) .

##### Optimizing the Link UI for Transfer 

The following Link configuration options are commonly used with Transfer:

*   [Account select](https://plaid.com/docs/link/customization/index.html.md#account-select) : The "Account Select: Enabled for one account" setting configures the Link UI so that the end user may only select a single account. If you are not using this setting, you will need to build your own UI to let your end user select which linked account they want to use with Transfer. When using [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) , this setting is mandatory.
*   [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) : This presentation mode shows the Link institution search screen embedded directly into your UI, before the end user has interacted with Link. Embedded Institution Search increases end user uptake of pay-by-bank payment methods and is strongly recommended when implementing Transfer as part of a pay-by-bank use case where multiple different payment methods are supported.

If you are using Transfer in a pay-by-bank use case where multiple payment methods are supported, see [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for recommendations on increasing the percentage of customers who choose to pay by bank.

##### Managing Proof of Authorization 

When making debit transactions, it is important to collect and store Proof of Authorization (POA) for NACHA compliance and to dispute return requests if necessary. If not using Transfer UI, you must collect your own POA and store it for at least two years. For more details on best practices for collecting and storing POA, see [NACHA guidance](https://www.nacha.org/system/files/2022-11/WEB_Proof_of_Authorization_Industry_Practices.pdf) and [Authorization requirements for ACH debits](https://support.plaid.com/hc/en-us/articles/32881513531671-What-are-my-obligations-as-an-ACH-Originator#h_01JYHCBZ492B106J7YF45ECKWR) . For exact requirements, [refer to the NACHA Operating Rules](https://support.plaid.com/hc/en-us/articles/32881513531671-What-are-my-obligations-as-an-ACH-Originator#h_01JXZS5HMS270QDFV7PKF9NJCC) .

While most customers collect and store their own authorization records, as an alternative, you can use Plaid's [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) for collecting ACH authorizations.

Transfer UI is a drop-in module for triggering transfer initiations while collecting the necessary authorization required. Simply invoke the UI when the user gets to the confirmation / submission stage of the payment, and Plaid handles the rest.

If an end user claims that a transaction is unauthorized and initiates a return request, their bank may contact Plaid to request a POA. POA requests will only ever be sent to Plaid, and not directly to you. Plaid will then contact you to request any additional information needed. You can provide this information via the [Tasks pane](https://dashboard.plaid.com/transfer/implementation-checklist) in the Dashboard.

##### Importing account and routing numbers 

If you are migrating from another payment processor and would like to import known account and routing numbers into Plaid, planning to implement a custom account linking UI, or intend to use wire transfers as a payment rail, contact your account manager about using the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint. This endpoint can be used to import previously-verified account and routing numbers and will return an `access_token` and `account_id` for a given account and routing number pair. Items created in this way will always have an authorization decision rationale code of `MIGRATED_ACCOUNT_ITEM`, since Plaid will be unable to assess transfer risk for these Items. This endpoint is not enabled by default; to request access, contact your Plaid Account Manager or [Support](https://dashboard.plaid.com/support) .

##### Expanding institution coverage 

To see if an institution supports Transfer, use the institution status page in the Dashboard or the [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint. If an institution is listed as supporting Auth, it will support Transfer.

Transfer supports all of the same flows as Auth, including the optional micro-deposit and database-based flows, which allow you to increase the number of supported institutions and provide pathways for end users who can't or don't want to log in to their institutions. Items created with Same Day micro-deposits, Database Insights, or Database Match will always have an authorization decision rationale code of `MANUALLY_VERIFIED_ITEM`, since Plaid will be unable to assess transfer risk for these Items. For more details about these flows and instructions on implementing them, see [Full Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) .

#### Authorizing a transfer 

Before a transfer is created, it must first be authorized. During the authorization step, Plaid's Transfer Risk Engine runs a series of risk and compliance checks that determine whether the transfer should proceed or be rerouted to a different payment method.

For more details about the specific checks that the Transfer Risk Engine runs and how to customize them for your business needs, see [Customizing Transfer Rules](https://plaid.com/docs/transfer/transfer-rules/index.html.md) .

To create a transfer authorization, call [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . You will be required to specify the `access_token` and `account_id` from the account linking step, as well as a `user.legal_name`, the transaction `amount`, the type of the transaction (`debit` or `credit`), and the transaction `network` (`ach`, `same-day-ach`, `rtp`, or `wire`). To request `wire` transfers, contact your Account Manager.

If you are using a [custom set of Transfer Rules](https://plaid.com/docs/transfer/transfer-rules/index.html.md#creating-additional-custom-rulesets) , you should also provide a `ruleset_key`.

For ACH transfers, an `ach_class` is also required. An `idempotency_key` is also strongly recommended to avoid creating duplicate transfers (or being billed for multiple authorizations). If you are a Platform Payments (beta) customer, you will also include an `originator_client_id`. For more details on these parameters, see [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) in the API Reference.

Failure to provide an `idempotency_key` when calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) may result in duplicate transfers when retrying requests. It is only safe to omit idempotency keys if you have already built and thoroughly tested your own logic to avoid creating or processing duplicate authorizations. Even if you have, idempotency keys are still strongly recommended.

Plaid will return `'approved'` or `'declined'` as the authorization decision, along with a `decision_rationale` and `authorization_id`. If the transaction is approved, you can proceed to [Initiate the transfer](https://plaid.com/docs/transfer/creating-transfers/index.html.md#initiating-a-transfer) .

To avoid blocking transfers, [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) will authorize transfers as `approved` by default in circumstances where Plaid can't accurately predict the risk of return. Always monitor the `decision_rationale` or customize your [Transfer Rules](https://plaid.com/docs/transfer/transfer-rules/index.html.md) to assess the full risk of a transfer before proceeding to the submission step.

Approved authorizations are valid for 1 hour by default, unless otherwise configured by Plaid support. You may cancel approved authorizations through the [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) endpoint if you no longer intend to use the authorization. Denied authorizations will have a `code` and `description` in the `decision_rationale` object that provide additional insight.

##### ACH SEC codes 

The ACH Standard Entry Class (SEC) code is represented in the Plaid API by the `ach_class` field and is required for all ACH transfers. SEC codes indicate the type of authorization the originator received in order to submit an ACH payment instruction into the ACH network. Using the incorrect code can result in a failed transfer authorization, ACH returns outside of the expected return window, or, if not remedied, eventual loss of access to Transfer.

Plaid permits only the following SEC codes to be utilized for ACH Transfers:

|  | ACH Debit | ACH Credit |
| --- | --- | --- |
| Consumer accounts | `web`, `tel`, `ppd` | `ppd` |
| Business accounts | `ccd` | `ccd` |

Transfer customers are approved for SEC codes based on the information supplied in the Transfer application. If an unapproved or unsupported SEC code is submitted, the transfer authorization request will fail with the error [TRANSFER\_FORBIDDEN\_ACH\_CLASS](https://plaid.com/docs/errors/transfer/index.html.md#transfer_forbidden_ach_class) .

###### SEC code definitions: 

`ccd` - Corporate Credit or Debit. The transfer moves funds to or from a business bank account

`ppd` - Prearranged Payment or Deposit. The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained from the consumer in person via writing, or through online authorization, or via an electronic document signing, e.g. Docusign. For example language for online authorization, see the [2025 NACHA Operating Rules](https://support.plaid.com/hc/en-us/articles/32881513531671-What-are-my-obligations-as-an-ACH-Originator#h_01JXZS5HMS270QDFV7PKF9NJCC) — Section 2.3.2, Authorization of Entries via Electronic Means. Can be used for credits or debits.

`tel` - Telephone-Initiated Entry. The transfer debits a consumer's bank account. Debit authorization has been received orally over the telephone via a recorded call.

`web` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits.

###### SEC codes and ACH returns 

SEC codes determine how long Receiving Depository Financial Institutions (RDFIs, i.e. counterparty banks) have to submit ACH returns for the transfers. ACH debit transfers labeled with consumer SEC codes (`web`, `tel`) permit RDFIs to submit unauthorized returns (R07, R10, R11, etc.) for up to 60 days after the effective date of the transfer, even if the debit was to a business bank account. If a consumer account is debited using a business SEC code (`ccd`), the RDFI can return the transfer for up to 60 days with an R05 return code because is it not proper to debit consumers using a business SEC code.

##### Handling user\_action\_required as a decision rationale code 

Sometimes Plaid needs to collect additional user input in order to properly assess transfer risk. The most common scenario is to fix a stale Item. In this case, Plaid returns `user_action_required` as the decision rationale code.

If it is important for your use case to always have an active connection to an end-user’s bank account to check the balance, then you should [set the outcome of this rule](https://plaid.com/docs/transfer/transfer-rules/index.html.md) to `REROUTE` and prompt the user to relink their account and restore the Item connection before initiating the transfer (see [Repairing Items in ITEM\_LOGIN\_REQUIRED](https://plaid.com/docs/transfer/creating-transfers/index.html.md#repairing-items-in-item_login_required-state) ). Otherwise, as long as you still have a valid ACH authorization to debit the end user account, you can use the default rule outcome of `ACCEPT` and proceed to initiate the transfer. Note that Plaid cannot retrieve the account balance on this Item until the Item connection is restored.

Previously, if an Item’s state was `ITEM_LOGIN_REQUIRED`, [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) would respond with `user_action_required` as the authorization decision. As of August 2025, the authorization will be either `approved` or `declined`, based on how you configure your ruleset.

##### Repairing Items in ITEM\_LOGIN\_REQUIRED state 

1.  Create a new Link token via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Instead of providing an `access_token`, you should set [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) in the request.
2.  Initialize Link with the `link_token`. Link will automatically guide the user through the necessary steps.
3.  You do not need to repeat the token exchange step in Link's `onSuccess` callback as the Item's `access_token` remains unchanged.

After completing the required user action, you can retry the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) endpoint with the same request body. You can even reuse the same `idempotency_key` as idempotency does not apply to `user_action_required` authorizations.

##### TRANSFER\_LIMIT\_REACHED 

If you are seeing transfer authorizations fail with the `TRANSFER_LIMIT_REACHED` rationale code when using Transfer in a new Plaid integration, ensure you have completed the [Transfer Implementation Checklist](https://dashboard.plaid.com/transfer) in the Dashboard in the Dashboard and have received full production access. If your Implementation Checklist has not been approved, your transfer limits will be set at very low levels intended only to allow testing rather than true production usage (maximum $10/transfer, $100/month).

#### Initiating a transfer 

After assessing a transfer's risk using the authorization engine and receiving an approved response, you can proceed to submit the transfer for processing.

Pass the `authorization_id`, `access_token`, `account_id`, and a `description` (a string that will be visible to the user) to the [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) endpoint. To make a transfer for less than the amount authorized, provide an optional `amount`; otherwise the transfer will be made for the full authorized amount. The `authorization_id` will also function similarly to an idempotency key; attempting to re-use an `authorization_id` will not create a new transfer, but will return details about the already created transfer. You can also provide the optional field `metadata` to include internal reference numbers or other information to help you reconcile the transfer.

[/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) will return `transfer_id` as well as the `transfer_status`. All transfers begin in a `pending` status. This status changes as the transfer moves through the payment network. Whenever the status is updated, a Transfer event will be triggered.

To learn more about the different stages of the transfer's lifecycle and tracking the status of the transfer, see [event monitoring](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md#event-monitoring) .

If submitting a `credit` transfer, you must have enough funds in your Ledger balance to cover the transfer amount.

##### Description field recommendations 

The description you send appears on your end-user's bank statement (after the bank prepends your company name and phone number). A clear, consistent value helps users recognize the payment and reduces "unrecognized charge" disputes and ACH returns.

###### Recommendations 

*   Describe the purpose of the transaction, not your company name; your company name will already be present on the line Item.
*   Avoid overly granular values (e.g., an invoice ID) that consume space but don't aid recognition. Put variable data in your internal metadata instead.
*   Avoid punctuation, non-ASCII characters, case-sensitive values, or emojis, as many banks will only display all-caps ASCII characters, with punctuation stripped.

| Use case | Suggested description | Notes / variants |
| --- | --- | --- |
| Consumer debit (pay-by-bank checkout, bill pay) | `PAYMENT` | Add abbreviation for cycle if helpful: `PAYMENT01`, `PAYMENTJUN` |
| Consumer credit / payout | `PAYOUT` | Refunds can use `REFUND` |
| Loan repayment | `LOANPAY` | Keeps it distinguishable from generic "payment" |
| Rent collection | `RENT` | Optional month tag: `RENTMAY` |
| Savings or investment sweep | `TRANSFER` |  |
| Internal transfer between user accounts | `TRANSFER` |  |
| Returned-transfer retry | `Retry 1` / `Retry 2` | These values are required for R01/R09 retries |

##### Handling errors in transfer creation 

If you receive a retryable error code such as a 500 (Internal Server Error) or 429 (Too Many Requests) when calling [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , you should retry the request; Plaid uses the `authorization_id` as an idempotency key, so you can be guaranteed that retries to [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) will not result in duplicate transfers.

A request to [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) may fail with a 500 error even if the transfer is successfully created. You should not assume that a 500 error response to a [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) call means that the transfer failed. As a source of truth for the transfer status, use [Transfer events](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) .

##### Initiating an Instant Payout via RTP or FedNow 

[Find out more about using Transfer for Instant Payouts in this 3-minute overview](https://www.youtube.com/watch?v=4tVKOXNqzGQ)

Initiating an Instant Payout transfer via RTP or FedNow works the same as initiating an ACH transfer. When initiating an Instant Payout transfer, specify `network=rtp` when calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . `rtp` as the network refers to all real time payment rails; Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary.

Roughly ~70% of accounts in the United States can receive Instant Payouts. If the account is not eligible to receive an Instant Payout, [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) will return an `INVALID_FIELD` error code with an error message that the account is ineligible for Instant Payouts. If you'd like to see if the account is eligible for Instant Payouts before calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , use the [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) endpoint.

Only `credit` style transfers (where you are sending funds to a user) can be sent using Instant Payout transfers.

##### Initiating a payout via wire 

Wire transfer capabilities are in early availability. To request access to wire transfers, contact your account manager.

To send a wire to a recipient end-user, you must first create an Item for the recipient using the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint and provide a `wire_routing_number` in addition to the `routing_number`. Wire routing numbers should be collected directly from end users. While the routing number for a wire payment is often the same as the routing number for an ACH payment, some institutions have different wire routing numbers. [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) , such as those used at Chase and PNC, cannot be used for wire transfers, so account numbers must be collected directly from end users at institutions that use TANs.

Authorization requests sent with a network of `wire` will only be attempted via wire and will not fall back to any other payment method. Only transfers of type `credit` can be sent using wire transfers.

Wires received by Plaid are processed hourly from 9 AM ET to 5 PM ET. The same-day cutoff time for wire initiation to Plaid is 4:30pm ET; wires submitted after that time will be processed on the next business day.

The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail.

Wire transfers may be subject to an incoming wire transfer fee from the recipient's bank, which is typically deducted by the bank from the amount received by the recipient. In the rare instance that a wire is rejected by the receiving bank (RDFI), you will be returned the original wire transfer amount, less a return fee (if any) from the receiving bank. The status of an RDFI-rejected wire will be `RETURNED` with [failure code](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer-get-response-transfer-failure-reason-failure-code) `REVERSAL` and a [failure reason description](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer-get-response-transfer-failure-reason-description) supplied by the banking partner. If a return fee is charged, the amount will be shown in the `wire_return_fee` field. In the Ledger, a new entry will be created with type `transfer`, description `wire return fee`, and an `amount` equal to the fee amount.

#### ACH processing windows 

Transfers that are submitted via the [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) endpoint will be submitted in the next processing window. For a Same Day ACH transfer, the cutoff time for the last window of the day is 3:30PM Eastern Time. For a Standard ACH transfer, the cutoff time is 8:30PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time to guarantee that it will be processed before the cutoff.

| Window | Plaid Cutoff | Settlement Date | Approx. Funds Availability to Plaid |
| --- | --- | --- | --- |
| Same Day #1 | 09:35 AM ET | T+0 (1:00 PM ET) | 1:00 PM ET |
| Same Day #2 | 01:50 PM ET | T+0 (5:00 PM ET) | 5:00 PM ET |
| Same Day EOD | 03:30 PM ET | T+0 (~6:00 PM ET) | End of day (~6:00 PM ET) |
| Standard | 08:30 PM ET | T+1 (~9:00 AM ET next day) | Morning of settlement date (~9:00 AM ET) |

Same Day ACH transfers submitted after 3:30PM Eastern Time and before 8:30PM Eastern Time will be automatically updated to be Standard ACH and submitted to the network in that following ACH processing window. This update applies to sweeps as well. This process minimizes the risk of return due to insufficient funds by reducing the delay between Plaid's balance check and the submission of the transfer to the ACH network. This ensures that the settlement time remains earlier than it would have been if the transfer had been submitted in next Same Day window; once the cutoff for Same Day ACH is missed, Standard ACH payments submitted before the cutoff settle to Plaid before the first Same Day settlement time of the next day.

ACH processing windows are active only on banking days. ACH transfers will not be submitted to the network on weekends or bank holidays. Any transfer created when an ACH processing window is closed will automatically be submitted to the network at the opening of the next processing window.

If a transfer is created when an ACH processing window is closed, the account's available balance or status may change between the [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) call and the time when the transfer is submitted to the network. To reduce your risk of ACH returns, wait until the processing window is open before calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) and [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , especially when submitting ACH credits.

See the [flow of funds](https://plaid.com/docs/transfer/flow-of-funds/index.html.md) overview for more details on how, and when, funds move.

#### Bank statement formatting 

Each bank has discretion in how they format an ACH, RTP, or FedNow transaction in their bank statements. The most common pattern used is `[Company Name] [Phone Number] [Transfer Description]`.

*   `[Company Name]` is the name provided in your Transfer application. This must match a legally registered name for your company.
    
*   `[Phone Number]` is the phone number that you provided in your Transfer application.
    
*   `[Transfer Description]` is the string that you passed into the description field of your [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) request.
    

To request a change to your phone number or company name, [file a support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/product-functionality) .

#### Canceling transfers 

To cancel a previously created transfer, use the Dashboard, or call the [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) endpoint with the appropriate `transfer_id`. Note that once Plaid has sent the transfer to the payment network, it cannot be canceled. Practically speaking, this means that Instant Payouts via RTP/FedNow cannot be canceled, as these transfers are immediately sent to the payment network. You can check use the `cancellable` property found via [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) to determine if a transfer is eligible for cancelation.

If the transfer is not `cancellable`, you may be able to undo it in another way. For undoing debit transfers, see [refunds](https://plaid.com/docs/transfer/refunds/index.html.md) . For information on undoing an ACH credit transfer, see [Escalating issues with ACH transfers](https://plaid.com/docs/transfer/troubleshooting/index.html.md#escalating-issues-with-ach-transfers) .

#### Sweeping funds to funding accounts 

There are two types of bank accounts in the Plaid Transfer system.

The first is a consumer checking, savings, or cash management account connected via Plaid Link, where you are pulling money from or issuing a payout to. In the Transfer API, this account is represented by an `access_token` and `account_id` of a Plaid Item. A "transfer" is an intent to move money to or from this account.

The second type of account involved is your own business checking account, which is linked to your Plaid Ledger. This account is configured with Plaid Transfer during your onboarding by using the details provided in your application. A "sweep" pushes money into, or pulls money from, a business checking account. For example, funding your Plaid Ledger account by calling [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) will trigger a sweep event.

To learn about all the different ways you can trigger a sweep event, see [Moving money between Plaid Ledger and your bank account](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-between-plaid-ledger-and-your-bank-account) .

Sweeps can be observed via the [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) and [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) endpoints. [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) will also return all events types, including sweep events.

#### Transfer limits 

When you sign up with Plaid Transfer, you will be assigned transfer limits, which are placed on your authorization usage. These limits are initially assigned based on the volume expectations you provide in your transfer application. When you successfully create an authorization using [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , the amount authorized will be counted against your limits. Authorized amounts that aren’t used will stop counting towards your limits if the authorization expires or is canceled (via [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) ).

Any authorization you attempt to create over your limits will be automatically declined.

| Limit | Debit | Credit |
| :-- | :-- | :-- |
| Single Transfer | The maximum amount of a single debit transfer authorization | The maximum amount of a single credit transfer authorization |
| Daily | The maximum amount of debit transfers you may authorize in a calendar day | The maximum amount of credit transfers you may authorize in a calendar day |
| Monthly | The maximum amount of debit transfers you may authorize in a calendar month | The maximum amount of credit transfers you may authorize in a calendar month |

Daily limits refresh every day and monthly limits refresh on the first day of the month at 12:00 AM EST.

##### Limit monitoring 

You can view your current limits on the “Account Details” page in the [Transfer Dashboard](https://dashboard.plaid.com/transfer) . You can monitor your usage against your daily and monthly limits via the Account Information widget on the Overview page. You can also monitor your authorization limits and usage through the Transfer APIs.

The [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) endpoint returns your configurations for each of the transfer limits. The [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) endpoint contains information about your daily and monthly authorization usage for credit and debit transfers.

Plaid will also send you automatic email notifications when your utilization is approaching your limits. If your daily utilization exceeds 85% of your daily limits or your monthly utilization exceeds 80% of your monthly limits, you will receive automated email alerts. These alerts will be sent to your ACH, Technical, and Billing contacts. You can configure those contacts via the [Company Profile](https://dashboard.plaid.com/settings/company/compliance?tab=companyProfile) page on the Plaid Dashboard.

Any call to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) that will cause you to exceed your limits will return the decision `"declined"` with the decision rationale code set to `TRANSFER_LIMIT_REACHED`. The rationale description identifies which specific limit has been reached.

##### Requesting limit changes 

If you need to change your limits for any reason, you can request changes via the [Account Details](https://dashboard.plaid.com/transfer/account-details) page in the Plaid Dashboard.

#### Peer to peer transfers 

Plaid Transfer does not support peer to peer transfers or transfers between two accounts held by the same person. For these use cases, see [Auth](https://plaid.com/docs/auth/index.html.md) .

---


# Transfer - Transfer Dashboard | Plaid Docs

Transfer Dashboard 
===================

#### Learn about the features available in the Plaid Transfer dashboard. 

#### Overview 

You can complete most transfer operational activities in the Transfer Dashboard. Many of these actions are also available via the [API](https://plaid.com/docs/api/products/transfer/index.html.md) .

A link to the Transfer Dashboard will appear in the Dashboard navigation after you have applied for access to [Transfer in the Production environment](https://dashboard.plaid.com/overview/production) . You can also access the Transfer Dashboard before applying for Production access by navigating directly to [dashboard.plaid.com/transfer](https://dashboard.plaid.com/transfer) .

The main overview page displays the following:

*   **Aggregate metrics**: total transfers, return rates, current volumes
*   **Account information**: limits (daily, monthly) and utilization to date. For ACH transfers, this also includes SEC codes you are approved for.
*   **Transfer activity**: table displaying all transfer, refund and sweep activity

(An image of "Plaid Transfer Dashboard showing aggregate metrics, account info, and transfer activity with search, filter, and export options.")

Home page of Transfer dashboard

Features available through the Dashboard include:

*   [Viewing and changing funding account information](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#adding-or-changing-funding-accounts) : You can self-serve linking a new funding account, deleting an account, or changing the default status of a funding account in the "Account details" page of the dashboard
*   [Moving money between your funding account and your Plaid Ledger](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-via-the-dashboard)
*   [Refunding](https://plaid.com/docs/transfer/refunds/index.html.md) or [canceling](https://plaid.com/docs/transfer/creating-transfers/index.html.md#canceling-transfers) transfers
*   Viewing and searching transfer details including events, statuses, and associated refunds, and viewing the trace numbers and event history of a transfer
*   Configuring [Transfer rules](https://plaid.com/docs/transfer/transfer-rules/index.html.md)

Creating and authorizing a transfer _cannot_ be completed from the Dashboard, nor can you link an end user's bank account from the Dashboard. These operations can only be completed using the API.

(An image of "Transfer details page showing $5 debit, options to simulate events, refund, or cancel. State: Settled. Activity log included.")

Transfer details page, including options to refund and cancel transfer. Because this transaction occurred in the Sandbox, options to manually change its state are shown.

#### Limits, reserves, and hold time 

Your initial limits, reserve requirements, and debit hold time (if applicable) are set at onboarding. As your business grows over time, you can request changes to your debit limits, credit limits, and/or debit hold time through the dashboard.

(An image of "Plaid Transfer Dashboard. Enter projected debit and credit volumes for limit change request. Options include single, daily, monthly.")

Plaid Transfer Dashboard Limits Change Request

If your requested changes require additional reserves, the amount will be indicated to you. Once the additional reserves are sent to Plaid (if applicable), the approved changes will be automatically implemented.

You can view your current limits, reserves, and debit hold time in the “Account Details” section of the dashboard:

(An image of "Plaid Transfer Dashboard showing account details, funding accounts, approved limits, hold times, and options to deposit or withdraw.")

Plaid Transfer Dashboard Limits and Hold Times

Wire instructions for funding the reserve account can also be found by clicking "Wire instructions" on the "Account details" section.

#### Ledger management 

From the Dashboard, you can see more details of your Ledger, add or withdraw money, and configure settings such as automated cashouts. For details, see [Moving money via the Dashboard](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-via-the-dashboard) .

#### Report extraction 

##### Transfer Activity Report 

In the Overview page of the Transfer section of the Plaid Dashboard, you can export a report with a list of transfers and sweeps as a .csv file by clicking "Export CSV."

(An image of "Popup for downloading transfers as CSV. Options: 'Yes, continue' and 'Cancel'. Background: transfer metrics and activity log.")

Plaid Transfer Dashboard CSV Export

Filters can be applied to the report by selecting **Filter**.

*   **Date**: Only transfers and sweeps that were created during the specified period (have `created_at` timestamps within the date range) will be included
*   **Transaction type**: Only the selected transaction types (transfers, sweeps, and/or refunds) will be included
*   **Status**: Only transfers or sweeps that currently (as of the report creation time) have the selected status(es) (`pending`, `posted`, `settled`, `funds available`, `returned`, `failed`, and/or `cancelled`) will be included

**In this report, you will see the following columns:** _Note:_ All timestamps utilize the timezone (EST or UTC) applied to the report.

| Column | Description |
| --- | --- |
| ID | The ID of the transaction type that occurred. For example, if the Type is `transfer`, then this field is the transfer ID. |
| Status | The status of the transaction type as of the time of the report export. Note that `funds available` is a status that is only applicable to debit transfers or debit sweeps. |
| Type | Whether the transaction was a `debit` or `credit` payment instruction. Transfers and sweeps can be debits or credits. Refunds are credits only. |
| Amount | The amount of the transaction. Amounts are signed. Debits have positive signed amounts (as debit transfers and sweeps increase the ledger balance). Credits have negative signed amounts (this activity decreases the ledger balance). |
| ACH class | For activity that was executed via the ACH network, the ACH Standard Entry Class (SEC) code of the transaction. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . |
| Network | The payment network used to fulfill the transaction. For debits, this will be either `same-day-ach` or `ach` (Standard ACH). For credits, this can be `rtp`, `wire`, `same-day-ach`, or `ach`. Note that if a Same Day ACH transfer was submitted after the cutoff, Transfer will downgrade the network to Standard ACH. Sweeps are not downgraded, so if a Same Day ACH cutoff is missed, the sweep will be retried the next morning for the first Same Day ACH cutoff of the day. |
| Account\_id | Plaid’s unique identifier for the account. |
| Account type | The type of bank account being debited or credited for a transfer. Either `checking` or `savings`. |
| User Legal Name | The legal name of the end user being debited or credited. Only populated for transfers and refunds. |
| User Email Address | The email address of the end user being debited or credited. Only populated for transfers and refunds. |
| User Routing Number | The routing number of the bank account being debited or credited. |
| Failure reason - ACH return code | If an ACH or Same Day ACH transfer has failed (returned), the return code (RXX). |
| Failure reason - Description | If an ACH or Same Day ACH transfer has failed (returned), a description for the return code. |
| Timestamps: Created / Pending / Posted / Settled / Funds Available / Returned / Failed / Cancelled | The timestamp of when the transfer, refund, or sweep progressed to this status. |
| Metadata | The contents of the key-value pair(s) included for the transaction (if applicable). |
| Refund Of | If the transaction is a refund, the ID of the debit transfer that the transaction is refunding |
| Refunded Amount | Refund amount issued. Refunds may be issued partially or completely. |
| Refund 1, 2, 3 | ID of the refund(s) issued. Multiple refunds can only be issued if the initial refund was not a complete refund of the debit transfer. |

_Note:_ The following columns are not applicable for customers on Plaid Ledger: `swept`, `return_swept`, `swept_settled`, `signed_sweep_amount`, `reserve_swept`, `signed_reserve_sweep_amount`, `signed_return_sweep_amount`.

##### Ledger balance Report 

Plaid provides reconciliation reports of all money moved into and out of your Plaid Ledger settlement balance. You can generate a custom report for any date range (up to 31 days) via the [Transfer account details](https://dashboard.plaid.com/transfer/account-details) Dashboard page.

In this report, you will see the following columns:

| Column | Description |
| --- | --- |
| Timestamp | The datetime, in the Eastern time zone, when the balance was impacted. |
| Originator Client ID / Client Name | Denotes the owner of the Plaid Ledger balance. For customers running a payments [platform](https://plaid.com/docs/transfer/platform-payments/index.html.md) , this will be your subcustomer’s client ID and business name. Otherwise, it’s your own client ID and business name. |
| Type | The type of activity impacting the balance:  
`transfer` indicates activity between the end consumer’s bank account (i.e accounts linked in your application’s product flows) and the Ledger balance.  
`sweep` indicates activity between your business checking accounts and the Ledger balance.  
`refund`s can occur on ACH debits to return funds to the consumer account.  
`distribute` indicates a movement of funds from one Plaid Ledger’s available balance to another Plaid Ledger’s available balance.  
`manual_adjustment` indicates this balance change was entered manually by Plaid. |
| ID | The ID of the activity that occurred. For example, if the Type is `transfer`, then this field is the transfer ID. |
| Description | A summary of the action that took place on this Type.  
`originated`: A request to originate the transfer, sweep, refund or distribute was received by Plaid.  
`returned`: An ACH return occurred.  
`canceled`: Payment execution was canceled via the API or dashboard.  
`converted_to_available`: Funds that were originally placed in a pending balance were moved to the available balance.  
`failed`: The attempt to move money failed.  
`dishonor`: a previous ACH return that came in was invalidated. When a dishonored return occurs, the transfer status will not change, but a row will be added to the report showing the funds from the dishonored return being added back to the Ledger balance.  
`facilitator_fee`: A fee was charged by the platform parent to its subcustomer.  
`distribute`: Funds were moved from one Plaid Ledger’s `available` balance to another Plaid Ledger’s `available` balance.  
`manual_adjustment`: A balance adjustment was entered manually.  
`incentive`: If “incentive” is prepended to a value above, it is referencing a pay by bank incentive that occurred on the transfer (for example, `incentive originated`). |
| Impacted Balance Type | The Ledger balance type that was impacted: `available`, `pending`, or `pending_to_available`. The latter denotes that both balances were impacted during a move of funds from `pending` to `available`. |
| Amount | The signed amount of the balance impact. `pending_to_available` is always a positive amount, noting the amount removed from `pending` and allocated to `available`. |
| New Pending Balance | The resulting value of the `pending` balance after this activity was applied to the relevant balance(s). |
| New Available Balance | The resulting value of the `available` balance after this activity was applied to the relevant balance(s). |

Using these columns, you can complete comprehensive financial reconciliation. For example: to see all the activity between your business checking account and the Ledger balance, filter for all rows where the column "Type" is `sweep`. To see refunds issued, filter for all rows where the column "Type" is `refund`. To see exactly when a specific ACH debit transfer’s funds became available in the Ledger balance, search for the row of type `transfer`, specifying the relevant `ID`, and look for its `pending_to_available` balance impact type.

##### Email reconciliation reports 

Plaid also provides optional monthly reconciliation reports via email, including aggregated details of funds movement activity for the month. To opt in to receiving these reports, contact your account manager.

#### Rules 

See [Customizing Transfer Rules](https://plaid.com/docs/transfer/transfer-rules/index.html.md) to learn how to configure the rules that will be run during authorization checks for debit transfers.

#### Tasks 

The Tasks pane will show any onboarding tasks you have not yet completed, such as selecting a hold time or sending your initial reserve amounts.

If Plaid is requesting that you provide [Proof of Authorization](https://plaid.com/docs/transfer/creating-transfers/index.html.md#managing-proof-of-authorization) for any disputed transactions, this will also be shown on the Tasks pane.

#### Dashboard permissions 

Transfer-specific Dashboard permissions can be set via the [team settings page](https://dashboard.plaid.com/settings/team/) . Transfer-specific permissions are as follows:

*   **Transfer Read & Write all** - Grants access to Transfer features.
    *   **Transfer Read** - Grants access to view Transfer Dashboard
    *   **Manage funding accounts** - Grants ability to manage Transfer funding accounts
    *   **Manage Ledgers** - Grants ability to manage Ledgers, including automated balance management settings
    *   **Manage transfer limits** - Grants ability to request changes to Transfer limits and hold times
    *   **Initiate refunds** - Grants ability to initiate refunds
    *   **Manage transfer Ledger funds** - Grants ability to deposit and withdraw funds from a Transfer Ledger

Note that these permissions only impact Dashboard access and do not apply to actions initiated via the API. A user who has the "Production Keys" permission or otherwise has access to Plaid Production API keys can still use the API to move funds in and out of the Ledger or initiate a refund, regardless of their Transfer Dashboard permissions.

---


# Transfer - Plaid Ledger flow of funds | Plaid Docs

Plaid Ledger flow of funds 
===========================

#### Understand how Transfer moves money with the Plaid Ledger 

#### Plaid Ledger overview 

The Plaid Ledger is a balance you keep with Plaid for use with the Transfer product. It is a settlement balance that all debit transfers settle into, and all credits are paid out from. Plaid provides several tools for moving money between your business checking account and your Ledger balance.

(An image of "Diagram of Plaid Ledger flow: Business account sweeps to Plaid ledger, transfers to customer account; details ACH credit/debit timing.")

Overview of the Plaid Ledger flow

By clicking on your Ledger in the Dashboard, you will be directed to the specific Ledger's page.

(An image of "Plaid Ledger Balance page showing summary, pending funds, and balance history with search and filters for event ID and date range.")

Plaid Ledger details page

From this page, you can:

*   View available and ending balances
*   View the release schedule of pending funds
*   Deposit funds into the Ledger
*   Withdraw funds from the Ledger to a linked funding account
*   View a real-time activity table of Ledger events and export the Ledger events as a CSV for reconciliation
*   Retrieve Ledger balance events

#### Receiving payments 

Your Plaid Ledger account has two balance values: `pending`, which contains funds that are in processing, and `available`, which contain funds that are available for use.

When receiving payments from your customers (via an ACH debit transfer), funds are placed in the `pending` balance as soon as your transfer is created. These funds become `available` after a hold period elapses. The hold period is typically 2-5 days after the transfer has settled; your specific hold period is unique to you and will depend on factors such as the reserve funds level you maintain with Plaid. The hold period will begin on the business day after the transaction emits the `settled` event and enters the `pending` state. Funds are typically made available at approximately 3:00PM ET on the last day of the hold period.

The projected date when funds in the `pending` state will be available is displayed on the Dashboard. It can also be obtained via any endpoint that returns a transfer object, such as [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) , in the `transfer.expected_funds_available_date` field. Once the funds have been made available, the [funds\_available event](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) will be emitted.

See below for an example schedule of when an ACH debit is withdrawn from a consumer's account (corresponding to the `settled` event), and when the funds are made available to you.

(An image of "Same Day ACH debit schedule: Funds withdrawal on Mon-Wed, available by Fri-Mon, based on time submitted (EST).")

Example schedule for a Same Day ACH debit.

(An image of "Standard ACH debit schedule: Funds withdrawn 1-3 days after submission, available on the 4th day based on submission time.")

Example schedule for a Standard ACH debit.

Note that the funds available date refers to when funds are available in your Ledger, not when the funds are withdrawn to your funding account. Withdrawing these funds to your funding account is performed via Same Day ACH and may take up to one additional business day.

If the ACH debit experiences a return or reversal, the funds will be clawed back from the Plaid Ledger balance. If the funds have already been made available and withdrawn to your business checking account, your available Ledger balance may go negative.

For more details on why a payment could be returned, see [Troubleshooting ACH Returns](https://plaid.com/docs/transfer/troubleshooting/index.html.md#ach-returns) .

#### Issuing payouts 

When issuing payouts to your customers (via ACH credit and RTP/FedNow transfers), the funds for the payout are deducted from your available balance and are sent out to your consumer in the next available ACH window, or immediately for RTP/FedNow. If there are not enough funds in your available balance to cover a transfer, then [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) will decline the transfer authorization with `NSF` (insufficient funds) as the `decision_rationale`.

You can check the value of the Plaid Ledger balance any time via the Dashboard or by calling [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) .

In order to avoid declined transfers, you should discuss with your company the level of funds you want to keep in the balance, and how you intend to refill the balance once it has been used.

How much money to keep in your Ledger will depend on your business cash flow constraints. It is recommended to keep a minimum of three days' worth of funds in your balance to cover activity taking place over the weekend, when ACH credits and wires are unavailable.

Even if your use case is for debit transfers only, you should retain enough funds in your Ledger to handle refunds and returns. Maintaining a zero or negative Ledger balance will prevent you from issuing refunds.

#### Moving money between Plaid Ledger and your bank account 

It is important to consider your strategy for moving funds between your Plaid Ledger balance and your business checking bank account. The Plaid Ledger balance cannot be used to store funds indefinitely.

Plaid provides four methods to manage your Plaid Ledger balance. Sweeps to or from your Ledger balance are priced the same as a transfer (for example, a `network=rtp` Ledger balance withdrawal is priced as an RTP transfer). If using Same Day ACH and your sweep amount is over the Same Day ACH transaction limit of $1M, Plaid will automatically break your sweep request into multiple transfers.

Each of the following methods will create a sweep object, viewable in [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) , and will emit `sweep.*` events for you to observe. See [Reconciling Transfers](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) for more details.

All methods of moving money to your Plaid Ledger, except for pushing funds via wire or ACH, are subject to a three business day hold. Funds will be made available at approximately 3:00 PM on the third business day after funds [settle](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-processing-windows) to Plaid. Note that this duration may not be the same as the the hold time applied to funds collected from debit transactions. Funds pushed by wire or ACH are available immediately upon settlement.

| Method | Optimizes for... |
| --- | --- |
| [Dashboard](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-via-the-dashboard) | Ad-hoc manual deposits/withdrawals |
| [API endpoints](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-via-api) | Custom deposit/withdrawal logic |
| [Automatic balance thresholds](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#automatically-managing-the-balance-level) | Ongoing hands-off management |
| [Pushing funds to Ledger via wire or ACH](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-via-ach-rtp-or-wire-transfer) | Immediate funds availability |

If you are a [Platform Payments (beta)](https://plaid.com/docs/transfer/platform-payments/index.html.md) customer, the API is the only method available for moving funds. For more details on moving money as a Platform, see [the Platform Payments documentation](https://plaid.com/docs/transfer/platform-payments/index.html.md#moving-money-for-end-customers) .

##### Moving money via the Dashboard 

You can use the Plaid Dashboard to manually trigger a deposit or withdrawal. Withdrawals will push the funds to your business checking account in the next Same Day ACH window. Deposits into your Plaid Ledger balance will pull from (debit) your business checking account using Same Day ACH and put the funds in your pending balance.

To move money via the Dashboard, you must have the "Manage Transfer Ledger Funds" permission, available via the [Team member setting page](https://dashboard.plaid.com/settings/team/members) .

Deposits that are pulled (debited) from your business checking account will be made available three business days after funds settle to Plaid. The deposit will display the `funds_available` status in the Dashboard once the funds are available to use in your Ledger.

You must ensure that your accounting department does not reject pulls from Plaid to deposit money into your Ledger balance. Contact your bank to ensure you accept incoming ACH debits from the following company or Originator ID: 1460820571.

###### Adding or changing funding accounts 

To add or change a funding account, navigate to the “Account Details” page of the Transfer dashboard and click on “Add account”.

(An image of "Dashboard UI showing 'Account details' section with a highlighted 'Add account' button for managing funding accounts.")

You will then be able to use Plaid Link to automatically connect your account and verify that it is open, active, and belongs to you.  For accounts that are unable to be linked via Plaid, there will be an option to manually enter account and routing information, and submit two bank statements to confirm your ownership of the account. Manually linked accounts will be reviewed by the Plaid team, and you will receive an email confirmation upon approval.

When new funding accounts are added, an email notification is sent to admins on the Plaid account notifying them of the change.

Within the dashboard, you can also specify which funding account to use as the default account for sweeps, give the account a friendly name, or remove the account.

##### Automatically managing the balance level 

You can set up automatic balance thresholds, allowing you to operate in a "set and forget" model. You can set both a minimum balance and a maximum balance. For the reasons described in [Issuing payouts](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#issuing-payouts) , it is not recommended to set a zero dollar minimum balance.

If you don't set a minimum balance, or set a minimum balance of zero dollars, Plaid will automatically debit your linked funding account if you have a negative available balance that will not be covered by pending incoming funds.

For example, if you have an available balance of -$500, and $300 in pending funds being released over the next three days, Plaid will debit your linked funding account by $200.

Every business day at 3:00 PM EST, Plaid will attempt to withdraw or deposit funds, depending on your configuration. If your available Ledger balance exceeds the maximum balance defined, Plaid will move money from your Ledger to your bank account using Same Day ACH. These funds should be available in your business checking account by 6:00 PM EST.

If your overall Ledger balance (including both pending and available balances) goes below your minimum balance, Plaid will move funds from your bank account to your Ledger using Same Day ACH. These funds will be placed in the pending balance, and made available 3 business days after the funds settle to Plaid.

To enable automatic refills and withdrawals, click the "settings" button on the [Ledger page](https://dashboard.plaid.com/transfer/ledgers/) . To change this setting, you must have the "Manage Transfer Ledger Funds" permission, available via the [Team member setting page](https://dashboard.plaid.com/settings/team/members) .

(An image of "Plaid dashboard showing Ledger summary, balance history, and settings for maintaining minimum balance in transfer flow.")

##### Moving money via API 

The API is the most flexible method for moving funds, as you can determine when and how your money moves: via Same Day ACH, standard ACH, or instantly via RTP/FedNow.

To deposit funds into your Plaid Ledger balance via API, use [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) . This endpoint will issue a [sweep](https://plaid.com/docs/transfer/creating-transfers/index.html.md#sweeping-funds-to-funding-accounts) to withdraw funds from your funding account. Once Plaid has received the funds (you may specify either standard or Same Day ACH), they will be made available after a three business day hold.

To see when the transfer is available in your Ledger, you can use the [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) or [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) endpoint to check for the `sweep.funds_available status`. You can also check the value of the Plaid Ledger balance via API by calling [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) .

You can retrieve Plaid Ledger balance events by calling the `transfer/ledger/event/list` endpoint with specified filter criteria. For example, you could search for all events for a specific `ledger_id`.

To withdraw funds from your Plaid Ledger balance via API, use [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) . You can choose the rails to use for the transfer: Same Day ACH, standard ACH, or instant.

##### Moving money via ACH, RTP, or wire transfer 

On the Ledger details page in the Dashboard, click the "Settings" icon in the upper right to view an account and routing number you can use to push funds to the Ledger via ACH credit, RTP or wire.

In this approach, you contact your bank (often via their website) to push funds to Plaid. Pushed funds become available for use in your Plaid Ledger as soon as they are received from the network. This method can only be used to deposit money into your Ledger; it cannot be used to withdraw funds. Incoming wires pushed to the Plaid Ledger are charged a separate fee, billed to your account. Incoming ACH and RTP credits pushed to the Plaid Ledger incur no fee. For more details, contact your Plaid Account Manager.

#### Maintaining multiple Ledger balances 

You can maintain multiple Ledger balances with Plaid. This is useful when you need separation between certain types of transactions for accounting purposes, or to connect different transactions with different bank accounts. For instance, you can use multiple Ledgers to:

*   Use separate funding accounts to issue credits and collect debits.
*   Keep accounting separate for different use cases, business units, or states where you operate.

Every Plaid client has one Ledger created and ready to use as their default Ledger to originate transfers or sweeps.

You can create additional Ledgers in the Plaid Transfer dashboard. From the [Ledgers page](https://dashboard.plaid.com/transfer/ledgers) , click "add". You will be prompted to assign a name for the Ledger and select one of your active funding accounts as the default funding account for this new Ledger. When you select a funding account for your Ledger, all of your automatic deposits and withdrawals flow to and from that funding account.

(An image of "Create a new ledger with fields for 'Ledger name' and 'Default funding account'. Checkbox to set as default ledger.")

Adding a Ledger

If you need to create more than ten total Ledgers, submit a [support ticket](https://dashboard.plaid.com/support/new/admin/account-administration) .

You can also view the detailed info of each Ledger via the Dashboard, including the Ledger’s id, name, balance, transaction history, and pending balance.

(An image of "Default Ledger Balance page showing a summary. Pending funds timeline and balance history are also visible.")

List of multiple Ledgers

Each Ledger has its own separate balance settings, including the funding account and minimum and maximum balance rules. You can share a single funding account across multiple Ledgers, or give each Ledger its own funding account.

Once created, additional Ledgers cannot be deleted. This is because Ledgers function as audit logs for your transaction history. If you no longer wish to use a Ledger, you can stop assigning transactions to it.

You can also move funds between Ledgers, by calling [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) . Note that only funds in a Ledger's available balance can be distributed to another Ledger.

##### Working with multiple Ledgers in the API 

If you have created multiple Ledgers, you should indicate which Ledger to use by specifying a `ledger_id` when calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) , and [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) . If no `ledger_id` is specified, Plaid will use your default Ledger. You can change which Ledger is considered the default in the Dashboard.

Each Ledger's balance history is reported separately.

Transfer objects, including `authorization`, `transfer`, `transfer_event`, `sweep` and `ledger`, will contain a `ledger_id` field, indicating which Ledger the object is associated with.

(An image of "Multi-ledger flow: Debit transfers to Pay-ins ledger, credit sweep to Funding account 1; Debit sweep from Funding account 2 to Pay-outs ledger, credit transfers to user accounts.")

Example multi-Ledger funds flow, using separate funds for issuing credits and collecting debits

(An image of "Flow diagram showing debit transfers from end user accounts to Ledgers 1, 2, and 3, then credits to Funding accounts 1 and 2.")

Example multi-Ledger funds flow, using separate funds for different states

---


# Transfer - Glossary | Plaid Docs

Glossary 
=========

#### Glossary of Transfer-specific terminology 

This glossary contains terms specific to the Plaid Transfer product. Most terms in this glossary are industry terms related to funds transfers.

For a general glossary of Plaid API terminology not related to the functionality of the Transfer product specifically, see the [Plaid Glossary](https://plaid.com/docs/quickstart/glossary/index.html.md) .

#### Payment rails 

##### ACH 

ACH (Automated Clearing House) is the primary US electronic network for processing bank-to-bank payments, such as direct deposits, bill payments, and transfers, typically settled in batches. It enables low-cost, reliable fund transfers between accounts, often taking 1–3 business days.

##### Standard ACH 

Standard ACH payments are payments sent over the ACH network without expedited processing. These typically complete within 1-3 business days. For transfers submitted via Plaid, the Standard ACH cutoff time is 8:30 PM Eastern Time. It is recommended to submit a request at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff.

##### Same Day ACH 

Same Day ACH uses the ACH network to allow eligible bank-to-bank transfers to be processed and settled on the same business day, typically within a few hours. For transfers submitted via Plaid as Same Day ACH, the Same Day ACH cutoff is 3:30 PM Eastern Time and the Standard ACH cutoff is 8:30 PM Eastern Time. It is recommended to submit a request at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. If a Same Day ACH transfer is processed after the Same Day ACH cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur Same Day ACH charges; this will apply to both legs of the transfer if applicable.

##### FedNow 

FedNow is a real-time payment service launched by the Federal Reserve that enables instant, 24/7/365 bank-to-bank transfers in the U.S., with immediate funds availability to recipients. Like RTP, FedNow only supports `credit` transfers. FedNow payments are irreversible once sent. Within the Plaid Transfer API, payments designated as `rtp` will be routed via either FedNow or RTP depending on availability. To check whether an institution supports real-time payments, use [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) .

##### RTP 

RTP, or Real Time Payments, is a U.S. payment rail administered by The Clearing House. RTP payments provide immediate, 24/7/365 settlement of payments between participating banks, with funds available to the recipient within seconds. Like FedNow, RTP only supports `credit` transfers. RTP payments are irreversible once sent. Within the Plaid Transfer API, payments designated as `rtp` will be routed via either FedNow or RTP depending on availability. To check whether an institution supports real-time payments, use [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) .

##### RfP 

RfP, or Request for Payment, is a mechanism by which you can initiate the equivalent of a debit funds transfer using the credit-only realtime RTP or FedNow rails. When an RfP is sent to an end user, they will be prompted to approve the RfP, which will then initiate a credit transfer to you for the given amount. To check whether an institution supports RfP, use [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) . Support for RfP within Plaid Transfer is currently in a closed limited beta. To express interest, contact your Account Manager.

##### Wire 

Wires, or wire transfers, are electronic funds transfers that move money directly between banks, typically within hours. Wires are only supported for credit transfers. Wires are irreversible once sent. The fee for wires is greater than for other payment methods. To request access to wires, contact your Account Manager. For more details on wires, see [Initiating a payout via wire](https://plaid.com/docs/transfer/creating-transfers/index.html.md#initiating-a-payout-via-wire) .

#### ACH terms 

##### NACHA 

NACHA, also styled as Nacha, is the North American Clearinghouse Association. NACHA manages the ACH network and establishes the rules and procedures around ACH, including what constitutes valid authorization for an ACH transaction and under what circumstances an ACH transaction may be returned or reversed. For more details on these topics, see [What are my responsibilities as an ACH originator?](https://support.plaid.com/hc/en-us/articles/32881513531671-What-are-my-obligations-as-an-ACH-Originator) .

##### ODFI 

The ODFI, or the Originating Depository Financial Institution, is the bank in an ACH transaction that initiates the transfer. The direction of funds movement is expressed from the perspective of the ODFI -- in the case of a debit transaction, the ODFI is the recipient of the funds, and in the case of a credit transaction, the ODFI is the sender. The ODFI's counterparty bank in the transaction is known as the RDFI, or the Receiving Depository Financial Institution. When you use Plaid Transfer to initiate a transaction, the ODFI is Plaid's Banking Partner.

##### RDFI 

The RDFI, or the Receiving Depository Financial Institution, is the bank in an ACH transaction that receives the transfer request from the ODFI. In the case of a debit transaction, the RDFI is the sender of the funds, and in the case of a credit transaction, the RDFI is the recipient. When using Plaid Transfer, the RDFI is typically your end user's bank where they linked their account. In the case of funds movement to or from your Plaid Ledger, initiated from a Plaid UI such as the Dashboard, Transfer API, or automatic balance transfers, the RDFI is your bank. (If moving money to your Ledger via an ACH transfer initiated from your bank, the RDFI is Plaid's Banking Partner and the ODFI is your bank.)

##### Recall 

A recall is a request submitted by the Originator to undo an ACH transfer that cannot be reversed or canceled. For more details, see [How do I request a recall?](https://support.plaid.com/hc/en-us/articles/32881719199767-How-are-ACH-Transfer-Investigations-Escalated#h_01JXZT0SCV68P41TP5MSG2E6M3) .

##### Return 

A return, or ACH Return, occurs when an ACH transaction is rejected or reversed by the receiving bank after it has been submitted, due to issues like insufficient funds, invalid account details, unauthorized debits, or other errors. Returns must be initiated within a specific timeframe (e.g., 2 banking days for most reasons, 60 days for unauthorized consumer debits). Each return comes with a reason code (e.g., R01 = NSF, R03 = No Account). For more details on dealing with returns, see [ACH Returns](https://plaid.com/docs/transfer/troubleshooting/index.html.md#ach-returns) . Returns will not occur when using RTP, FedNow, or wire transfers, as these funds transfer methods are irreversible.

##### Reversal 

An ACH reversal is a request submitted by the Originator to the ODFI to cancel or correct a previously submitted ACH transaction that has already been processed, typically due to an error such as duplicate payment, wrong amount, or incorrect account number. Reversals must be initiated within 5 banking days of the original settlement date. For details, see [How do I request a reversal?](https://support.plaid.com/hc/en-us/articles/32881719199767-How-are-ACH-Transfer-Investigations-Escalated#h_01JXZT18R8C24G31SB3C1P7PMR) . Reversals are not allowed when using RTP, FedNow, or wire transfers, as these funds transfer methods are irreversible.

#### Payment statuses 

For more information on payment statuses and their timelines, see the [Transfer status lifecycle](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md#transfer-status-lifecycle) .

##### Cancelled 

The payment was canceled by the requestor while the payment was in a pending state. No money was moved. This is a terminal state. For more information, see [Canceling transfers](https://plaid.com/docs/transfer/creating-transfers/index.html.md#canceling-transfers) .

##### Failed 

A failed payment was rejected by either Plaid or the financial institution. No money was moved. This is a terminal state. For more information on handling failures, see [Errors and troubleshooting](https://plaid.com/docs/transfer/troubleshooting/index.html.md) .

##### Funds available 

Funds from the transfer have been released from hold and applied to the Ledger's available balance. This state is only applicable to ACH debits. This is the terminal state of a successful debit transfer.

##### Pending 

A pending payment has not yet been submitted to the payment network and may still be canceled. For information on when payments are submitted to the network, see [ACH processing windows](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-processing-windows) and [Initiating a payout via wire](https://plaid.com/docs/transfer/creating-transfers/index.html.md#initiating-a-payout-via-wire) .

##### Posted 

A posted payment has been submitted to the payment network but has not yet settled. For information on settlement timelines, see the [Transfer Status Lifecycle](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md#transfer-status-lifecycle)

##### Settled 

A payment is settled when funds have been transferred between the sending financial institution and the receiving financial institution. Settlement does not guarantee that the institution has released the funds to the recipient; a settled payment may still appear as a pending transaction in the recipient's or sender's bank account. This is a terminal state for a successful payment. However, a settled payment can still be returned. For information on settlement timelines, see the [Transfer Status Lifecycle](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md#transfer-status-lifecycle) .

##### Returned 

A payment has experienced an [ACH return](https://plaid.com/docs/transfer/glossary/index.html.md#return) . This is a terminal state. For more details on dealing with returned payments, see [ACH Returns](https://plaid.com/docs/transfer/troubleshooting/index.html.md#ach-returns) .

#### Other Transfer terms 

##### FBO account 

Plaid's FBO ("for benefit of") account is used to hold money used in transfer operations. This is the bank account where you send money to fund your Ledger, and where money is held until it is disbursed to your account; it is the bank account where the money that backs your Ledger is actually stored. The FBO designation indicates that while Plaid is the custodian of the funds, the funds are held "for the benefit of" (i.e., belong to) Plaid's Transfer customers.

##### Funding account 

The business bank account belonging to your organization and linked to your Ledger. The funding account is used as the ultimate source of funds for credit transfers and the ultimate recipient of the funds for debit transfers.

##### Ledger 

The Ledger, or the Plaid Ledger, is a balance you keep with Plaid for use with the Transfer product. It is a settlement balance that all debit transfers settle into and all credits are paid out from. For details on working with the Ledger, including moving money into and out of the Ledger or maintaining multiple Ledgers, see [Plaid Ledger flow of funds](https://plaid.com/docs/transfer/flow-of-funds/index.html.md) .

##### Originator 

The Originator is the party who is requesting a funds transfer. When using Plaid Transfer, you are the originator of all transfers you request unless you are using Platform Payments (beta). For more details on the distinction between Originators and Platforms, see [Originators vs Platforms](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) .

##### Sweep 

A sweep is a transfer of money, typically automated or pre-programmed, between two accounts held by the same party to optimize the usage or availability of funds. For example, a brokerage account might automatically sweep money from a cash account to a money market account to earn higher interest while maintaining liquidity. In the context of Plaid Transfer, a sweep refers to any money movement between your Plaid Ledger(s) and your bank account. To learn more about sweeps, see [Sweeping funds to funding accounts](https://plaid.com/docs/transfer/creating-transfers/index.html.md#sweeping-funds-to-funding-accounts) .

---


# Transfer - Transfer Overview | Plaid Docs

Introduction to Transfer  
==========================

#### Intelligently process transfers between accounts 

Get started with Transfer

[API Reference](https://plaid.com/docs/api/products/transfer/index.html.md) [Quickstart](https://github.com/plaid/transfer-quickstart) [Demo](https://plaid.coastdemo.com/share/66d783135f0f8b245d4153fe?zoom=100) [Application Process](https://plaid.com/docs/transfer/application/index.html.md)

#### Overview 

Plaid Transfer (US only) is a flexible multi-rail payment platform designed for companies looking to add or improve their bank payment solution. Transfer provides all of the necessary tools to easily send and manage ACH, RTP, RfP, wire transfer, and FedNow transactions, including:

*   Easy integration with a single API: Avoid the need for multiple service providers. Connect user accounts, make smarter transaction decisions, manage risk, and move money—all through a single Plaid integration.
    
*   Fast settlement, simplified reconciliation: Sweep transaction funds into your treasury account quickly and balance your books with an intuitive reconciliation report.
    
*   Multi-rail routing: Dynamic routing between RTP, RfP, and FedNow. Fall back to same day ACH if needed. Easily enable new payment rails with a single setting, using the same integration code.
    
*   Streamlined operational support: Manage daily operations with dashboards to easily monitor transfer activity.
    
*   Payment risk reduction: Minimize your payment failure and ACH return rates by using Plaid's risk engine.
    

Plaid Transfer provides a full-service funds transfer solution for payers and recipients within the US. If you prefer to use a third party payment processor, your use case is not supported by Transfer (e.g. a marketplace or money transfer app), or if you or your counterparties are outside the US, see [Plaid Auth](https://plaid.com/docs/auth/index.html.md) instead for a bring-your-own-processor funds transfer solution. See [Auth and Transfer comparison](https://plaid.com/docs/payments/index.html.md#auth-and-transfer-comparison) for a side-by-side product comparison.

For similar end-to-end payment capabilities in Europe, see [Payments (Europe)](https://plaid.com/docs/payment-initiation/index.html.md) .

### Integration overview 

[Prefer to learn by watching? Watch this introduction to Transfer in 3(-ish) minutes!](https://www.youtube.com/watch?v=GPcW6Htrl5o)

The process below defines the highest level steps to move money via Transfer and monitor for updates.

Prerequisite: Prior to beginning your integration, [complete the Transfer Application](https://plaid.com/docs/transfer/application/index.html.md) and receive approval. You can begin integrating with Sandbox while waiting for approval.

1.  [Initialize](https://plaid.com/docs/transfer/creating-transfers/index.html.md#account-linking) a Link session to link a consumer bank account
    
2.  [Authorize](https://plaid.com/docs/transfer/creating-transfers/index.html.md#authorizing-a-transfer) and [create](https://plaid.com/docs/transfer/creating-transfers/index.html.md#initiating-a-transfer) the transfer
    
3.  (Optional) [Monitor](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) for updates to the transfer
    
4.  (Optional) [Customize Transfer Rules](https://plaid.com/docs/transfer/transfer-rules/index.html.md) to adjust authorization thresholds for your use case
    

Additionally, implement additional features such as [refunds](https://plaid.com/docs/transfer/refunds/index.html.md) , [recurring transfers](https://plaid.com/docs/transfer/recurring-transfers/index.html.md) , or [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) as needed.

---


# Transfer - Platform Payments | Plaid Docs

Platform Payments 
==================

#### Learn how to use Transfer as a Payments Platform 

Get started with Platform Payments

[API Reference](https://plaid.com/docs/api/products/transfer/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md)

#### Overview 

Platform Payments is still in beta. If you are interested in Platform Payments, [contact sales](https://plaid.com/contact) or your Plaid account manager.

Plaid is currently accepting beta applications for Payment Platform reseller partners (e.g. platforms that power bill pay or pay-by-bank services for their customers). Other use cases, such as crowdfunding, peer-to-peer payments, or marketplaces, are not currently eligible to join the Platform Payments beta program.

If you are not a Platform, see [Transfer](https://plaid.com/docs/transfer/index.html.md) for Plaid's general transfer documentation. If you're unsure whether you're a Platform, see [Originators vs Platforms](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) .

Platform Payments (beta) is for reseller partners that resell Plaid services to end-customers. An example of this is a payment processor who is adding ACH to their offering. They create an SDK for the end-customer that can be integrated into their own application.

Benefits of Platform Payments include:

*   Easy end-customer onboarding: Use Plaid's KYB and out-of-the-box onboarding UI.
    
*   Efficient fund management: Choose whether to sit directly in the flow of funds or move funds directly to your customers. You'll be able to move your money more efficiently and safely, optimizing cash flow and reducing any unnecessary delays. By default, funds are safely isolated for each of your merchants.
    
*   Instant payouts: Platform Payments provides access to both instant payments (via RTP and FedNow) and same-day ACH through a unified integration.
    
*   Streamlined account reconciliation: Reconcile transfers within your customers' bank accounts, as well as with yours, and track funds at every step as they move through the payment flow.
    
*   Simplified facilitator fees: Via Plaid's API-based solution for taking facilitator fees for your platform, you can collect fees without having to invoice your customers.
    

Platform Payments cannot be used with [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) or [Recurring Transfers](https://plaid.com/docs/transfer/recurring-transfers/index.html.md) .

#### Integration process 

Platform Payments is built on top of Transfer. It's recommended you review the Transfer [integration steps](https://plaid.com/docs/transfer/index.html.md) and use the Platform Payments documentation as a supplement.

At a high level, the instructions for integrating with Platform Payments are the same as for integrating with Transfer, with two exceptions:

*   You will need to onboard your end-customers (your customers, also known as originators).
*   When calling most endpoints in the Transfer API, you will specify an `originator_client_id`.

Reseller partners must use their customer's `client_id` and `secret` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to link end-user Items for Transfer. They should use their own `client_id` and `secret` when calling other Transfer endpoints.

###### Other Transfer terminology 

**End-customers** (also known as **originators**) are your customers, on whose behalf funds are being transferred. These are identified by an `originator_client_id`.

**Users** or (**end-users**) are the customers of your end-customers, the people who are paying in to Transfer. These accounts are identified by an `access_token`.

#### Onboarding end customers 

Platforms use Plaid for onboarding decisioning of their end-customers via an out-of-the-box KYB solution that includes a UI you can integrate into your onboarding flow. This seamlessly enables your end-customer to input their business information and agree to Plaid's terms and conditions for money movement.

After a customer submits their information, Plaid will review it and reach out directly to them for any additional details, if needed. You can check the status of this approval at any time. Once approved, the end-customer can start processing payments.

The steps below outline the flow for onboarding end customers:

1.  Create an end customer: call [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) with `auth` specified, followed by [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) .
2.  Obtain an onboarding URL by calling [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) . Send this onboarding URL to your customer to have them complete the onboarding questionnaire.
3.  Obtain Plaid's onboarding decision by calling [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) .

##### Creating an end-customer 

Call [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) , making sure to specify `auth` (not `transfer`) in the `products` array, and then call [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) .

You will use the `end_customer.client_id` of the customer as the value of the `originator_client_id`.

In the Sandbox environment, create customers using [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) . For more details, see [Testing in Sandbox](https://plaid.com/docs/transfer/sandbox/index.html.md#testing-platform-payments-end-user-onboarding) .

When you create an end-customer, you will obtain an `originator_client_id`. Be sure to persist this value in relation to the end-customer.

Even after your customer has been enabled, you will need to proceed through the KYB process before funds can be transferred on their behalf.

##### Send end-customer through Plaid onboarding 

Send the end-customer's client ID to the [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) endpoint. This will return a unique `onboarding_url` that you should use to onboard the end-customer.

```bash
curl -X POST https://sandbox.plaid.com/transfer/questionnaire/create \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": "${PLAID_CLIENT_ID}",
   "secret": "${PLAID_SECRET}",
   "originator_client_id": "6a65dh3d1h0d1027121ak184",
   "redirect_uri": "https://example.com"
 }'
```

```bash
{
  "onboarding_url": "https://plaid.com/originator/hIFGXx1zM5pFerygu7lw",
  "request_id": "saKrIBuEB9qJZno"
}
```

Make sure to provide the URL only to the specific end-customer it is meant for. The URL is valid for 2 months but becomes invalid once the end-customer completes the flow.

Within the onboarding questionnaire, the end-customer will input their relevant business details, usage expectations, and bank account details, and then agree to Plaid's terms and conditions for money movement. After submitting the form, they are automatically redirected back to the provided redirect URI.

##### Obtain Plaid's onboarding decision 

Plaid will review the end-customer's information and follow up with them directly if we require any additional details. You can check the status of the decision by calling [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) or [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) and looking at the `originator.transfer_diligence_status`.

Once the end-customer's status is `approved` and they have completed any implementation checklist items required, you can begin moving money for them.

#### Moving money for end-customers 

This section discusses moving money for your end-customers' accounts. You also have your own Plaid Ledger, which is associated with your `client_id`; to learn about funds transfers between your own Ledger and funding account, see [Moving money between Plaid Ledger and your bank account](https://plaid.com/docs/transfer/flow-of-funds/index.html.md#moving-money-between-plaid-ledger-and-your-bank-account) .

Each [Plaid Ledger](https://plaid.com/docs/transfer/flow-of-funds/index.html.md) is linked to a funding account, which is a regular business checking account. For your end-customers, the account details for the account they would like to use as a funding account are collected during onboarding and persisted against their `originator_client_id`. A Ledger will automatically be created for each of your end-customers.

##### Pay-ins 

Debits created by calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) followed by the [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) endpoint for your customer will increase their Ledger balance. Incoming funds that are not yet available (i.e. whose hold period has not yet elapsed) are in the `pending` portion of the balance. Once the hold period elapses, at 3pm EST on the final release date, these funds will shift to the `available` portion of the balance, where they are held until you pay them out.

To create this withdrawal from the Plaid Ledger balance, call [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) endpoint, specifying the `originator_client_id`, `amount`, and rail (e.g. `ach`, `same-day-ach`, `rtp`). This will create a sweep and move the funds from your customer's Ledger balance to their funding account at the next available window (or instantly if done via RTP).

##### Returns 

Any return could result in a negative balance in the end-customer's Plaid Ledger if there are not funds in the balance to cover the return. As the Platform, you are liable for making end-customers' balances whole, and should have strategies in place to recover funds from them. For example, you should first try calling [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) to bring the balance out of negative. Should these deposits fail, Plaid will reach out to you to make the balance whole.

In the future, Plaid will add configurations to automatically recoup funds from your end-customer to bring it out of a negative balance, or to use your Ledger balance in the event of a failure.

If the issue of end-customers maintaining negative balances is persistent or severe enough, this will impact your access to the Transfer product.

##### Payouts 

Funds must be available in your end-customer's Ledger balance in order to issue a payout. To issue the payout, create a deposit by calling [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) and providing the `originator_client_id`, the `amount`, and rail (e.g. `ach`, `same-day-ach`, `rtp`). This will create a sweep and move funds from the end-customer's funding account to their Ledger balance at the next available window. These funds will land first into the `pending` balance, and will become `available` for use at 3PM EST 3 days after the `sweep.settled` event is emitted. For same-day ACH sweeps, this will be 3 business days (for example, a deposit issued at 9am EST on Monday is available at 3PM EST on Thursday).

The logic for when and how much to deposit into the end-customer's Plaid Ledger will be dependent on your use-case.

After funding your end-customer's Ledger, you can create credits for them by calling [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) followed by [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , which will decrease their available Ledger balance and issue the payment in the next upcoming ACH window, or instantly for RTP/FedNow.

Any ACH returns or processing failures will return the funds back into the `available` balance.

#### Collecting fees as a Platform 

If your application takes a per-transfer fee for every incoming payment, you are able to specify and track that using the facilitator fee feature. When calling [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) with `type=debit`, specify the `facilitator_fee` parameter. The amount specified in the `facilitator_fee` will be allocated towards the Platform's Ledger balance instead of the end-customer's.

For example, if you specify a $2 facilitator fee on a $10 ACH debit, then $8 will be placed in the end-customer's Ledger pending balance, and $2 will be placed in your Platform pending balance. Both will be converted to the available balance after the hold time expires. If the debit results in an ACH return, funds are clawed back from both balances.

Facilitator fees are available only on ACH debit transfers. Facilitator fees are not supported on end-customer deposits or withdrawals to or from a Ledger balance. To support a custom fee structure (such as taking a fixed monthly fee from your end-customer), you can use [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) .

#### Moving funds between Ledgers 

Platform customers can move money between their own Platform-level Ledger balance and the Ledger balance of any of their end-customers by using [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) (beta).

Note that this endpoint is in an early development phase as Plaid gathers customer feedback. There are currently no events emitted within [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) for Ledger distributions, nor is there an API to fetch a specific distribution object. Instead, Ledger distributions are available in the CSV reconciliation reports in order to fully audit all movements of funds. If you are interested in using the [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) endpoint, contact your Plaid Account Manager.

---


# Transfer - Tracking transfer status | Plaid Docs

Tracking transfer status 
=========================

#### Monitor for updates to transfers, sweeps, and refunds 

#### Transfer status lifecycle 

All transfers initiated via ACH (including refunds and sweeps) move through a set of `status`es that correspond to phases in the ACH lifecycle. Understanding these lets you forecast funds availability and surface accurate messaging to your end users.

| Status | Typical timing after /transfer/create | ACH Network Phase | Business significance / recommended actions |
| --- | --- | --- | --- |
| pending | Instant (<1s) | Payment instruction received by Plaid and queued for processing | Transfer can still be canceled until it moves to posted. Safe to show "processing" to users. |
| posted | At cutoff of applicable ACH window (e.g. 9:35 AM, 1:50 PM, 3:30 PM, or 8:30 PM ET) | Payment instruction released to the ACH Network via ODFI | Transfer has been submitted to the payment network and can no longer be canceled. |
| settled | Same Day ACH: ~8:00 PM ET T; Standard ACH: ~9:00 AM ET T+1 | The Federal Reserve settles funds between sending and receiving banks | For debits: funds have been withdrawn from the debited account and settled to Plaid's FBO bank account. For credits: funds have been withdrawn from Plaid's FBO bank account and settled to the receiving institution. |
| Funds available | 2-5 business days after settlement | N/A | For debits only. Funds released from pending and applied to ledger's available balance. Debits that do not return will remain in this status. |
| failed | Seconds to minutes after a failure | Entry rejected before leaving Plaid/ODFI (e.g. compliance or validation failure) | No funds movement occurred. Investigate cause and optionally retry. |
| cancelled | Seconds after calling [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | Client-initiated cancellation accepted | The transfer will not be submitted to the payment network. |
| returned | Typically T+2 - T+5 (can be up to 60 days for consumer debits) | Receiving FI returns the debit or credit with a return code | For ACH debits: funds are withdrawn from Ledger (pending or available depending on timing). For ACH credits: funds are returned to the Ledger’s available balance. Take action per return code. |

#### Event monitoring 

Plaid creates a transfer event any time the `transfer.status` changes. For example, when a transfer is sent to the payment network, the `transfer.status` moves to `posted` and a `posted` event is emitted. Likewise, when an [ACH return](https://plaid.com/resources/ach/ach-return/) is received, a `returned` event will be emitted as the `transfer.status` is updated. By monitoring transfer events, you can stay informed about their current status and notify customers in case of a canceled, failed, or returned transfer. When `transfer.status` moves to `settled`, you can safely expect that the consumer can see the transaction reflected in their personal bank account.

Events are also emitted for changes to a sweep's and refund's `status` property. These events follow an `[object].[status]` format, such as `sweep.posted` and `refund.posted`.

For a list of all event types and descriptions, see the [API Reference](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer-event-sync-response-transfer-events-timestamp) .

#### Ingesting event updates 

Most integrations proactively monitor all events for every transfer. This allows you to respond to transfer events with business logic operations, such as:

*   Kicking off the fulfillment of an order once the transfer has settled
*   Making funds available to your end consumers for use in your application
*   Monitoring returns to know when to claw these services back, or retry the transfer

To do this, set up Transfer webhooks to listen for updates as they happen. You must register a URL to enable webhooks to be sent.

You can do this in the [webhook settings page](https://dashboard.plaid.com/team/webhooks) of the Plaid Dashboard. Click **New Webhook** and specify a webhook URL for a "Transfer Webhook". You must be enabled for Production access to Transfer in order to access this option. To confirm that your endpoint has been correctly configured, you can trigger a test webhook via [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) . Only one webhook URL can be set per environment at a time; if you register multiple Transfer webhook receiver endpoints for a given environment, the webhooks will be sent to only one of the registered URLs.

Now, every time there are new transfer events, Plaid will fire a notification webhook.

```json
{
  "webhook_type": "TRANSFER",
  "webhook_code": "TRANSFER_EVENTS_UPDATE",
  "environment": "production"
}
```

To receive details about the event, call [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) .

```json
{
  # Return the next 20 transfer events after the transfer event with id 4
  "after_id": "4",
  "count": "20"
}
```

You can then store the highest `event_id` returned by the response and use that value as the `after_id` the next time you call [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) to get only the new events.

Note that webhooks don't contain any identifying information about what transfer has updated; only that an update happened. As an alternative to listening to webhooks, your application could also call [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) on a regular basis to process the most recent batch of Transfer events.

For a real-life example of an app that incorporates the transfer webhook and tests it using the [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) endpoint, see the Node-based [Plaid Pattern Transfer](https://github.com/plaid/pattern-transfers) sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer webhook handler can be found in [handleTransferWebhook.js](https://github.com/plaid/pattern-transfers/blob/master/server/webhookHandlers/handleTransferWebhook.js) and the test which fires the webhook can be found at [events.js](https://github.com/plaid/pattern-transfers/blob/master/server/routes/events.js) .

#### Filtering for specific events 

Calling [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) will get a list of transfer events based on specified filter criteria. For example, you could search for all events for a specific `transfer_id`. If you do not specify any filter criteria, this endpoint will return the latest 25 transfer events.

You can apply filters to only fetch specific event types, events for a specific transfer type, a specific sweep, etc.

```json
{
  "transfer_events": [
    {
      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
      "transfer_amount": "12.34",
      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
      "transfer_type": "credit",
      "event_id": 1,
      "event_type": "pending",
      "failure_reason": null,
      "origination_account_id": null,
      "originator_client_id": null,
      "refund_id": null,
      "sweep_amount": null,
      "sweep_id": null,
      "timestamp": "2019-12-09T17:27:15Z"
    }
  ],
  "request_id": "mdqfuVxeoza6mhu"
}
```

#### Reconciling sweeps with your bank account 

As Plaid moves money in and out of your business account as you process transfers and cashout the Plaid Ledger balance, you might want to match the account activity in your bank account with the associated transfers.

Plaid will deposit or draw money from your business checking account in the form of a [sweep](https://plaid.com/docs/transfer/creating-transfers/index.html.md#sweeping-funds-to-funding-accounts) . This means that any time you are interacting with your bank statement, you are viewing sweeps, not specific transfers.

To match an entry in your bank account with a sweep in Plaid's records, Plaid ensures the first 8 characters of the sweep's `sweep_id` will show up on your bank statements. For example, consider the following entries in your bank account from Plaid:

| Entry | Amount | Date |
| --- | --- | --- |
| PLAID 6c036ea0 CCD | \-$5,264.62 | November 18, 2022 |
| PLAID ae42c210 CCD | $2,367.80 | November 16, 2022 |
| PLAID 550c85fc CCD | $6,007.49 | November 10, 2022 |

You can use this 8 character string from your bank statement to search for the sweep via [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) , or in your Plaid Transfer dashboard.

To follow the lifecycle of a sweep, and monitor funds coming into and out of your business checking account due to Plaid Transfer activity, observe the `sweep.*` events in the [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) endpoint. To view all sweeps, use [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) .

To see if a given debit transfer has been included in a sweep transaction, check the transfer's `status` field. If it has been swept, it will have the `funds_available` status.

#### Performing financial reconciliation audits 

For information on performing financial reconciliation audits, see [Report extraction](https://plaid.com/docs/transfer/dashboard/index.html.md#report-extraction) .

#### Flow of funds 

Understand how your money moves through the Plaid network

[Learn more](https://plaid.com/docs/transfer/flow-of-funds/index.html.md)

---


# Transfer - Recurring transfers | Plaid Docs

Recurring Transfers 
====================

#### Learn how to set up and use recurring ACH transactions 

Recurring transfers allow you to automatically originate fixed amount ACH transactions with a regular interval according to a schedule you define. Plaid currently supports intervals with an arbitrary number of weeks or months.

Once you set up the recurring transfer, Plaid automatically originates the ACH transaction on the planned date, defined by the recurring schedule. You can look up and cancel recurring transfers. You may also receive updates about the recurring transfer itself, as well as each individual transfer originated by the recurring transfer.

Recurring transfers cannot be used with [Platform payments](https://plaid.com/docs/transfer/platform-payments/index.html.md) .

#### Creating a recurring transfer 

Before creating a recurring transfer, you should be familiar with creating one-time transfers. See [Creating Transfers](https://plaid.com/docs/transfer/creating-transfers/index.html.md) .

Use [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) to create a new recurring transfer. The request body is very similar to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , except that you will provide an additional `schedule` parameter.

The `schedule` defines the start date and the recurring interval. Optionally, you may provide an end date, which is the last day, inclusively, that an ACH transaction can be originated. If the end date is not set, the recurring transfer remains active until it is canceled.

The recurrence interval is calculated by multiplying `interval_unit` by `interval_count.` For example, to set up a recurring transfer that's originated once every 2 weeks, set interval\_unit = "week" and interval\_count = 2.

The `interval_execution_day` parameter indicates which day in the week or month that you expect a new ACH transaction to be originated.

For a weekly recurring schedule, `interval_execution_day` should be an integer ranging from 1 to 5, representing Monday through Friday.

For a monthly recurring schedule, `interval_execution_day` should be either a positive integer ranging from 1 to 28, indicating the 1st through 28th day of the month; or a negative integer ranging from -1 to -5, where -1 is the last day of the month, -2 is the second-to-last day of the month, and so on.

For example, a transfer with `interval_execution_day` of `-1` in 2025 would be executed on January 31, February 28, March 31, April 30, June 2 (because the last day of May 2025 is a Saturday; see [Weekend and bank holiday adjustment](https://plaid.com/docs/transfer/recurring-transfers/index.html.md#weekend-and-bank-holiday-adjustment) ), June 30, etc.

#### Canceling a recurring transfer 

To cancel a recurring transfer, use [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) and provide the `recurring_transfer_id` of the recurring transfer you wish to cancel.

If you cancel a recurring transfer on the same day that a new ACH transaction is supposed to be originated, it is not guaranteed that this transaction can be canceled.

Once a recurring transfer has been cancelled, the `status` field associated with the `recurring_transfer_id` will be `cancelled`.

#### Execution of scheduled recurring transfers 

Before each instance of a recurring transfer is executed, Plaid will automatically perform the same authorization check performed by [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . If the check succeeds, the transfer will proceed, and Plaid will notify you via a [RECURRING\_NEW\_TRANSFER](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) webhook. If the check fails, the transfer will not be executed, and Plaid will notify you via a [RECURRING\_TRANSFER\_SKIPPED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_transfer_skipped) webhook.

If a recurring transfer instance is skipped due to a failed authorization check, it will not be retried. Subsequent transfers will be attempted as normal.

Once the last scheduled instance of a recurring transfer has been executed (or attempted to be executed), the `status` field associated with the `recurring_transfer_id` will move from `active` to `expired`.

##### Weekend and bank holiday adjustment 

If the planned origination date falls on a weekend or a bank holiday, Plaid automatically adjusts it to the next available banking day, provided that the adjusted date is on or before the schedule's `end_date`.

This means if the origination date after adjustment falls after the recurring schedule's `end_date`, it will not be originated. We recommend you always choose a banking day as the `end_date` in the schedule if it's needed.

#### Receiving updates on a recurring transfer 

Plaid sends following webhook events regarding a recurring transfer:

*   [RECURRING\_NEW\_TRANSFER](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) when a new ACH transaction is originated on the planned date.
*   [RECURRING\_TRANSFER\_SKIPPED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_transfer_skipped) when Plaid is unable to originate a new ACH transaction on the planned date due to a failed authorization, such the account having insufficient funds.
*   [RECURRING\_CANCELLED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) when the recurring transfer is cancelled by Plaid.
*   For all transfers created through recurring transfer, [TRANSFER\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer_events_update) webhook events are also sent so that you can receive updates on each individual ACH transaction.

The transfers created through recurring transfer appear in the response of [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) and can be queried by [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) given a `transfer_id`. The `recurring_transfer` object also has a `transfer_ids` field, containing the ids of the transfers originated by this recurring transfer. To get details of transfer instances created from a recurring transfer, you can call [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) on a schedule and store the new `transfer_id`s, then call [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) on those id(s) to retrieve the transfer details.

#### Recurring transfers and PNC TAN expiration 

If you have a recurring transfer that lasts for over a year and where the end user's account is held at PNC Bank, you may need to send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) at least once a year to avoid disruption of the transfer schedule. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) .

#### Testing recurring transfers 

See [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) .

---


# Transfer - Refunds | Plaid Docs

Refunds 
========

#### Issue a refund for an ACH debit 

Refunds allow you to quickly and easily refund customers for ACH debit transfers.

#### Creating a refund 

Use [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) or the Plaid Dashboard transfer details pane to create a refund for a debit transfer. Pass the ID of the transfer you'd like to refund as `transfer_id` in the request, and specify the amount of the refund with the `amount` field. The amount of a refund can't exceed the amount of the refunded transfer.

(An image of "Plaid Dashboard UI showing refund initiation form with fields for net amount, refund amount, confirmation, and a Confirm button.")

Initiate refunds from the Plaid Dashboard UI.

You can create multiple refunds for a transfer as long as the total amount does not exceed the amount of the original transfer.

Refunds come out of the available balance of the ledger used for the original debit transfer. If there are not enough funds in the available balance to cover the refund amount, the refund will be rejected. You can create a refund at any time. Plaid does not impose any hold time on refunds.

If you issue a refund for a debit transfer within 2 business days of the settlement date of the original debit transfer, the debit could still return for insufficient funds. Debits to consumers can also return as “unauthorized” for up to 60 calendar days.

If a debit transfer that you have refunded is later returned by the payment network, you may be debited for both the return and for the refund. Plaid will not reimburse you for these costs.

Transfers in a `cancelled`, `failed`, or `returned` state cannot be refunded.

#### Canceling a refund 

Use [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) or the Dashboard to cancel a refund. You can only cancel refunds before they've been submitted to the ACH network for processing.

#### Refund events 

Plaid creates an event any time the status of a refund changes. Refund events are prefixed with `refund.` and have a non-null `refund_id` in the event object. See [event monitoring](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md#event-monitoring) for more information on monitoring events.

Refund events will have many of the same characteristics as the original payment. They will have the same `account_id`, as well as having the same `transfer_type` and a positive transfer amount. For example, if you were to refund $5 from a customer's `debit` transfer of $100.00, that refund will be displayed in the events queue with a `debit` transfer type and a `"5.00"` transfer amount.

---


# Transfer - Reserves | Plaid Docs

Reserves 
=========

#### Learn about Transfer reserves requirements 

Reserves are static funds held by Plaid to mitigate the financial risks associated with ACH debit transactions. Holding funds in reserve with Plaid operates on a sliding scale, meaning that increasing the amount in reserves can lead to progressively lower ACH debit hold times and increased limits, with a few exceptions.

#### Why reserves are required 

Reserves cover potential losses that Plaid may experience as a result of processing ACH debits. Reserves are a common industry practice used by payment processors and financial institutions to ensure that businesses have sufficient balance to return funds to end-users when necessary.

ACH debits have financial risk because they can fail ("return") after settlement occurs. Even after funds have been transferred to Plaid, they can be returned back to the debited account up to 60 days after the transaction. This can occur due to a variety of reasons, including insufficient funds in the debited account; the debited account being inactive, closed, or blocked; or the consumer claiming the debit was unauthorized. If a customer does not have sufficient funds to cover the return, that will cause a negative balance and a potential loss to Plaid.

#### How Plaid uses reserves 

If a Ledger's available balance goes negative due to ACH debit returns, the balance will usually recover after a few days due to pending funds coming off hold. However, if the amounts of the available and pending balances are insufficient to cover the returned amounts, then Plaid will debit your linked funding account for that Ledger to recover the balance.

Plaid will draw from reserves only if the owed amounts could not be recovered via payment processing or auto-initiated debits to the associated funding account.

#### Funding your reserves 

During your onboarding process, Plaid will calculate the required amount of reserve funds and options for number of hold days based on your use case, maximum transaction size, and expected volume of transactions.

These options will be presented to you in your [Implementation checklist](https://plaid.com/docs/transfer/application/index.html.md#implementation-checklist) . After selecting the number of hold days, you can see the corresponding reserve amount required.

Your implementation checklist will show you the necessary details to initiate a wire transfer for the required reserve amount. Once Plaid receives the funds, they will be automatically allocated to your reserve balance.

Your current reserve balance is displayed in the [Dashboard](https://dashboard.plaid.com/transfer) . See the "Account Information" section to view the total amount currently held.

#### Changes to your reserve balance 

The required reserve amount may be adjusted based on changes to ACH debit hold times, transaction limits, or return rates.

If adjustments to your reserve amount are necessary, your Plaid Account Manager will communicate this to you and provide guidance. For further assistance or to adjust your reserves, please contact your Plaid Account Manager directly.

---


# Transfer - Testing in Sandbox | Plaid Docs

Transfer Sandbox 
=================

#### Use Sandbox to test your transfer integration 

While all newly created teams can use Transfer in Sandbox by default, some older teams may need to be manually enabled. If you receive an error indicating that the product is not enabled for your account when attempting to use Transfer in the Sandbox environment, contact Support or your Plaid Account Manager to request access.

#### Introduction to Sandbox 

Sandbox is Plaid's environment for testing using fake data. For more details about getting started with Sandbox environment, including how to skip the Link flow in Sandbox with `/sandbox/item/public_token/create`, and testing non-Transfer-specific functionality such as Item errors, see [Sandbox](https://plaid.com/docs/sandbox/index.html.md) .

#### Simulating money movement, events, and webhooks 

When creating transfers in Sandbox, see the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) documentation on how to generate approved or declined authorization responses.

Any cutoff times applied in Production will also apply in the Sandbox environment. For example, creating a same-day ACH transfer in Sandbox after 3:30 pm ET will automatically update the transfer to standard ACH.

In the Sandbox environment, no real banks are involved and no events are triggered automatically. By default, all transfers, refunds, and sweeps created in Sandbox remain at the `pending` status until you actively change them. This can be most easily accomplished through the Plaid Dashboard, where you can simulate next steps and common failure scenarios for any transfer that you've created in the Sandbox environment.

(An image of "Plaid Dashboard UI: Buttons to simulate sandbox transfer events. Options: 'Next Event,' 'Failure,' and 'Return.'")

You can simulate many Sandbox events using the Plaid Dashboard.

If you would like to change the status of a transfer through the API, you can call the following endpoints to simulate events and fire transfer webhooks manually.

| Action to simulate | Simulation endpoint |
| --- | --- |
| Transfer events | [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) |
| Refund events | [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) |
| Ledger withdrawals sweep events | [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) |
| Ledger deposits sweep events | [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) |
| Ledger pending-to-available funds movements | [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) |
| Webhooks | [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) |

When you change the status of a Sandbox transfer, either through the Dashboard or the API, the corresponding webhook will not fire. You must use the [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) API to send a Transfer webhook in Sandbox.

For a full list of transfer simulations available in Sandbox, see [Sandbox endpoints](https://plaid.com/docs/api/sandbox/index.html.md) .

For a general overview of the Plaid Sandbox environment, see [Sandbox overview](https://plaid.com/docs/sandbox/index.html.md) .

#### Automatic Sandbox simulations 

In addition to manual simulations, the Sandbox environment supports automatic state transitions for transfers, refunds, and sweeps (deposits and withdrawals) when using specific test amounts. These special amounts trigger predefined state transitions without requiring manual intervention through the Dashboard or API.

Once you initiate a transfer with any of these specific amount values, the transfer's stages will be immediately simulated. The appropriate webhooks for Sandbox transfer events will be fired, and you can fetch the events through [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) . You can also view the events' progression on your Transfer Dashboard, on the details page for the specific transfer.

In Production, transfer state changes can take minutes to hours depending on processing time. Sandbox simulations provide immediate state transitions for testing purposes.

##### Transfer state transitions 

Creating Sandbox transfers with the specified amounts via [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) will result in automatic state transitions.

| Amount | State Transition Path |
| --- | --- |
| $11.11 | pending → posted → settled → funds available (ACH debits only) |
| $22.22 | pending → failed |
| $33.33 | pending → posted → settled → funds available (ACH debits only) → returned (R01) |
| $44.44 | pending → posted → settled → funds available (ACH debits only) → returned (R02) |
| $55.55 | pending → posted → settled → funds available (ACH debits only) → returned (R16) |
| $66.66 | pending → posted → settled → returned |

##### Refund state transitions 

Creating Sandbox refunds with the specified amounts via [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) will result in automatic state transitions.

| Amount | State Transition Path |
| --- | --- |
| $1.11 | pending → posted → settled |
| $2.22 | pending → failed |
| $3.33 | pending → posted → settled → returned |

##### Sweep State Transitions 

Creating Sandbox sweeps with the specified amounts via [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) and [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) will result in automatic state transitions.

| Amount | State Transition Path |
| --- | --- |
| $111.11 | pending → posted → settled → funds available (deposits only) |
| $222.22 | pending → failed |
| $333.33 | pending → posted → settled → funds available (deposits only) → returned |
| $444.44 | pending → posted → settled → returned |

#### Testing Plaid Ledger flow of funds 

While testing Plaid Ledger in Sandbox, you can always call the following endpoints at any time to verify expected behavior:

*   [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) to validate the transfer status change
*   [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) to validate the deposit/withdrawal status change
*   [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) to validate the Ledger balance change

#### Wire transfers 

In Sandbox, all customers are enabled for wire transfers in order to facilitate testing. Having access to wire transfers in Sandbox does not mean you are enabled for wires in Production. To request access to wire transfers in Production, contact your Account Manager.

##### Issuing payouts with a Plaid Ledger 

###### Adding funds to the Plaid Ledger 

All new Plaid Ledgers have a starting balance of $100 in Sandbox. Once this is depleted, or if you wish to simulate a larger transfer, you will need to fund the Ledger before testing the payout.

1.  Call [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) to create a sweep that adds funds to a Plaid Ledger balance. The funds will immediately show up in the `pending` balance.
2.  Call [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) with `sweep.posted` as the `event_type`.
3.  Call [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) with `sweep.settled` as the `event_type`. This will move your sweep to `settled` status.
4.  Call [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) in order to simulate the passage of time and transition the funds from `pending` to `available`.

###### Issuing a payout 

1.  Call [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) with `type=credit` and your desired network. To simulate an insufficient funds failure, call [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) with an amount larger than your current available balance.
2.  Call [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . This will immediately create a transfer and decrement the available balance.

##### Receiving payments via Plaid Ledger 

1.  Call [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) with `type=debit`.
2.  Call [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . This will immediately create a transfer and increment your pending balance in the Plaid Ledger.
3.  Call [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) with `posted` as the `event_type`.
4.  Call [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) with `settled` as the `event_type`. This will move your transfer to `settled` status. The funds will remain in `pending` until the hold is elapsed.
5.  Call [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) to simulate the passage of time and convert the Ledger balance to `available`. If you are a Platform Payments customer, this will convert all pending balances in all Plaid Ledgers.
6.  Call [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) to create a sweep that withdraws funds from the Plaid Ledger balance. The endpoint will immediately decrement the available balance and create a sweep with `pending` status.
7.  Call [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) with `sweep.posted` as the `event_type`.
8.  Call [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) with `sweep.settled` as the `event_type`. This will move your sweep to `settled` status.

In Production, transfer and sweep status will be updated automatically to reflect the real processing status, and the `pending` balance will automatically become `available` after the client-specific hold day.

##### Simulating a return with Plaid Ledger 

1.  Follow steps 1-3 in [Receiving payments via Plaid Ledger](https://plaid.com/docs/transfer/sandbox/index.html.md#receiving-payments-via-plaid-ledger) section to create a debit and move it to `posted`.
2.  (Optional) To simulate a return after the funds were made available, follow steps 4-5 as well. If you would like to simulate a return before the funds were made available, omit this step.
3.  Call [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) with `returned` as the `event_type`. This will move the transfer status to returned and decrement pending balance, which you can verify by calling [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) .

###### Testing Instant Payouts 

Testing Instants Payouts works the same way as testing ACH Transfers.

To test the [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) endpoint in Sandbox, log in using the `user_good` user Sandbox account (see [Sandbox simple test credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#sandbox-simple-test-credentials) for more information), and use the first 2 checking and savings accounts in the "First Platypus Bank" institution (ending in 0000 or 1111), which will return `true`. Any other account will return `false`. If using a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) , set `numbers.ach_routing` to `322271627` in order to return `true`.

#### Setting balances 

You can customize the starting balance and certain other data for a linked account by using a Sandbox [custom user](https://plaid.com/docs/sandbox/user-custom/index.html.md) . The easiest way to set a custom balance is to use a test user in the [custom users repo](https://github.com/plaid/sandbox-custom-users/) . Using one of the example files, modify the starting balance, then follow the instructions in the repo's README to add the user to your Sandbox.

#### Simulating recurring transfers 

In the Sandbox environment, recurring transfers can be simulated by using a `test_clock` object.

A `test_clock` is a mock clock that has a `virtual_time` field, indicating the current timestamp on this test clock. You can attach a `test_clock` to a `recurring_transfer` in Sandbox by providing a `test_clock_id` when calling [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) .

You can advance the `virtual_time` on a `test_clock` to a higher value by calling [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) , but you can never decrease the `virtual_time`.

When a test clock is advanced, all active recurring transfers attached to this clock will generate new originations as if the time had elapsed in Production. For instance, assuming a test clock is attached to a weekly recurring transfer, if the test clock is advanced by 14 days, you should see two new transfers being created.

Note that advancing a test clock does not change the status of the transfer objects created by a recurring transfer. Transfers will stay in `pending` status unless you call [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) to simulate a transfer status update.

##### Sample Sandbox recurring transfer scenarios 

1.  Create a test clock using [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) , with a `virtual_time` of `"2022-11-14T07:00:00-08:00"`, which is 2022-11-14 7AM PST (Monday).
    
2.  Create a weekly recurring transfer on every Tuesday using [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) with the `test_clock_id` returned from step 1. The recurring schedule starts on 2022-11-15, and ends on 2022-11-30.
    
3.  Advance the test clock to `"2022-11-15T23:59:00-08:00"`, which is the end of day 2022-11-15 PST (Tuesday).
    
4.  Since we advanced the test clock to the last minute of Tuesday and the recurring transfer is also scheduled on every Tuesday, we expect to see 1 transfer being created. Inspect the recurring transfer created in step 2 with [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) . Confirm the `transfer_ids` field now has 1 element, and the `status` field is `"active"`.
    
5.  Advance the test clock to `"2022-11-29T23:59:00-08:00"`, which is the end of day 2022-11-29 PST (Tuesday).
    
6.  Inspect the recurring transfer created in step 2 with [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) . Confirm that the `transfer_ids` field now has 3 elements, and the `status` field is now `"expired"`.
    
7.  Advance the test clock to `"2022-12-06T23:59:00-08:00"`, which is the end of day 2022-12-06 PST (Tuesday).
    
8.  Inspect the recurring transfer created in step 2 with [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) . Confirm that the `transfer_ids` field still has 3 elements, and the status field remains `"expired"`.
    

#### Testing Platform Payments end-user onboarding 

The following test scenarios are specific to [Platform customers](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) only.

In Sandbox, [Reseller partners](https://plaid.com/docs/transfer/platform-payments/index.html.md) must use [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) instead of the [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) and [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) endpoints that they would use in Production.

##### Simulating onboarding end-customers 

In Sandbox, you can create an end-customer by calling the [/transfer/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorcreate) and then [/transfer/questionnaire/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferquestionnairecreate) . You will not be able to go through the onboarding UI in Sandbox: the test end-customer will automatically be approved. If you need to test the onboarding UI, you can do so in Production.

---


# Transfer - Customizing Transfer Rules | Plaid Docs

Customizing transfer rules 
===========================

#### Learn how to understand and customize Transfer rules 

Before they can be initiated, transfers must be authorized by Plaid's authorization engine, known as the Transfer Risk Engine. The Transfer Risk Engine is a series of checks that are run when [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) is called and determine whether the Transfer should proceed or be rerouted to a different payment method.

The Transfer Risk Engine is based on a series of rules. These include a [mandatory set](https://plaid.com/docs/transfer/transfer-rules/index.html.md#default-authorization-decisions) of risk and compliance checks, which can apply to both debit and credit transfers, as well as a configurable set of rules, which are displayed in the Dashboard. These configurable rules are used only for debit transfers and do not apply to customers who use Transfer for payouts (credits) only.

(An image of "Transfer Rules UI showing a set of default rules.")

The transfer Rules configuration page, with a set of default rules loaded

Each rule produces a result:

*   `ACCEPT` and proceed with the transaction. The `decision` from [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) will be `approved`.
*   `REROUTE` the customer to a different payment method. The `decision` from [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) will be `declined`.

The Dashboard rules are evaluated top‑to‑bottom; the first rule whose criteria is met sets the result. Every ruleset must include a fallback rule that always matches all remaining transactions.

You can customize many of these rules to meet your business's needs.

If you are a Signal customer, you will configure rules in the [Signal section of the Plaid Dashboard](https://plaid.com/docs/signal/signal-rules/index.html.md) . The Transfer Risk Engine will use the rule results from Signal instead of using the rules in the Transfer Dashboard.

If you are already calling the [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) endpoint before initiating a [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call, you should contact your account manager and request to disable the real-time balance check in the Transfer Risk Engine, to avoid making redundant balance checks.

#### Default ruleset for real-time balance checks 

The Transfer Risk Engine performs a real-time balance check of the end-user account when evaluating debit transfers. Plaid provisions a default ruleset for balance checks containing four rules that cover the most common balance‑related scenarios.

| Rule order | Condition | Result | Decision Rationale Code | Explanation | Configurability |
| --- | --- | --- | --- | --- | --- |
| 1 | Is Item Login Required **equals** `TRUE` | `ACCEPT` | `ITEM_LOGIN_REQUIRED` | Item connection is [broken](https://plaid.com/docs/errors/item/index.html.md#item_login_required) but can be restored using [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . A transfer can still be processed without restoring the Item, but Plaid cannot retrieve balance information until the Item is restored. See [Repairing Items in ITEM\_LOGIN\_REQUIRED state](https://plaid.com/docs/transfer/creating-transfers/index.html.md#repairing-items-in-item_login_required-state) . | Result can be edited. |
| 2 | Account Verification Status **in** \[`Database Insights Pass With Caution`\] | `ACCEPT` | `MANUALLY_VERIFIED_ITEM` | Item was manually verified via [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md#overview) and result was ["pass with caution"](https://plaid.com/docs/auth/coverage/database-auth/index.html.md#understanding-verification-status-and-name-score) . Balance can never be checked on this Item. | Result can be edited. |
| 3 | Balance Fetch Succeeded **equals** `false` | `ACCEPT` | `ERROR` | Plaid was unable to fetch the balance of the account for reasons not covered in the previous two rules. You can retry this authorization request later to re-attempt fetching the balance. | Result can be edited. |
| 4 | Available or Current Balance **≤** `Transaction Amount` | `REROUTE` | `NSF` | Account balance is likely to be insufficient for the transaction amount. | Result can be edited.  
Rule can be deleted. |
| 5 | _(Fallback)_ Remaining transactions | `ACCEPT` | `null` | Transaction did not meet the condition for any other rule above. | Fallback rule. Cannot be edited or deleted. |

The default ruleset is designed to let you proceed with processing transfers by default. When Plaid is unable to fetch the account balance, the default ruleset produces an `ACCEPT` result.

You can edit the rule outcomes to be more conservative based on your risk tolerance and ongoing return rates. For example, in the case of high NSF returns, you may want to `REROUTE` transactions when balance fetches fail, when the Item connection is broken, or when the result of Database Auth is `database_insights_pass_with_caution`.

#### Creating additional custom rulesets 

If you have your own set of rules you would like to use for balance checks, you can create a custom ruleset via the Plaid Dashboard. You can create multiple rulesets and have different rulesets applied in different situations.

For example, you could create a ruleset with stricter rules for first time users (such as not proceeding with the Transfer when the balance could not be fetched) and a separate ruleset with more lenient rules for returning users, allowing you to better balance your risk and user experience.

You can not override the compliance checks that would result in a `RISK` code.

To create a ruleset:

1.  In the Plaid Dashboard, navigate to [Transfer → Rules](https://dashboard.plaid.com/transfer/risk-profiles/)
2.  Click **Create ruleset** and give it a descriptive name. This will also create a unique key that you will use to refer to this ruleset later in your code.
3.  You can select from **Generate a set of recommended rules**, which will give you the default set of rules that you can use as a starting point, or **Create rules from scratch**.
4.  Add rules using the **Create rule** dialog:
    *   Choose a **condition**.
    *   Select the **result** (`ACCEPT` or `REROUTE`).
5.  Drag rules to set order of evaluation.
6.  Save the ruleset and toggle **Enabled** to activate it.

(An image of "Transfer UI showing the user creating a new rule to reject transfers where the Item is in a login required state and the transfer value is greater than $75.")

Creating a new Transfer rule with the Create Rule dialog.

As you create and modify rulesets in the Plaid Dashboard, the Dashboard will display back‑tested performance for these new rulesets (counts of historical matching transactions and return‑rate estimates) so you can gauge the impact of these changes before going live. You can view the performance for any specific rule by clicking on the "..." icon next to the rule and selecting **View Performance**.

#### Using rulesets during transfer authorization 

To evaluate a transfer against a custom ruleset, pass the `ruleset_key` in your [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call. If you do not pass in a `ruleset_key`, the Risk Engine will use the `default` ruleset.

Plaid will assess the transfer against the corresponding ruleset, and the `authorization` object in the API response will indicate if the authorization is approved or declined, along with a decision rationale code. Transfers that result in an `ACCEPT` value will have an `approved` authorization decision, and transfers that result in `REROUTE` will have a `declined` decision.

```bash
"authorization": {
  "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"
  "decision": "approved",
  "decision_rationale": {
    "code": "ITEM_LOGIN_REQUIRED",
    "description": "Unable to pull required information on account needed for authorization decision due to item staleness."
  }
...
}
```

When any of the rules within the ruleset are triggered, the `decision_rationale.code` in the response will indicate which rule condition was met. Note that when the decision rationale is `null`, this means that the transfer passed through to the fallback rule without triggering any of the other rules.

When any of the non-fallback rules in a ruleset are triggered, the `decision_rationale.code` in the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) response will indicate which rule condition was met. See the [table](https://plaid.com/docs/transfer/transfer-rules/index.html.md#default-ruleset-for-real-time-balance-checks) above to map a `decision_rationale.code` to a default rule.

#### Default authorization decisions 

##### All transactions 

The following authorization decisions are applied to all applicable transfers sent to Plaid for authorization. This includes a mandatory set of risk and compliance checks that cannot be disabled or modified.

| Transfer Type | Scenario | Authorization Decision | Decision Rationale Code |
| --- | --- | --- | --- |
| Debit, Credit | Items successfully created through manual verification (micro-deposits or database authentication) are approved by default for processing because there is no active data connection to the Item. | `approved`\* | `"MANUALLY_VERIFIED_ITEM"` |
| Debit, Credit | Items created through [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) are always approved for processing because there is no active data connection to the Item. See [Importing Account and Routing numbers](https://plaid.com/docs/transfer/creating-transfers/index.html.md#importing-account-and-routing-numbers) . | `approved` | `"MIGRATED_ACCOUNT_ITEM"` |
| Debit, Credit | Transfer exceeds a limit, such as a monthly or daily transaction limit (see [TRANSFER\_LIMIT\_REACHED](https://plaid.com/docs/transfer/creating-transfers/index.html.md#transfer_limit_reached) ). | `declined` | `"TRANSFER_LIMIT_REACHED"` |
| Debit, Credit | The Item's `[verification_status](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-status)` is `database_insights_fail`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `verification_expired`, or `verification_failed`. | `declined` | `"RISK"` |
| Debit, Credit | The user's device activity indicates fraud | `declined` | `"RISK"` |
| Debit, Credit | The user's IP address is in an OFAC-sanctioned country | `declined` | `"RISK"` |
| Debit, Credit | There are excessively high rates of insufficient funds, administrative, and/or unauthorized returns associated with the account across the Plaid network. | `declined` | `"RISK"` |
| Credit | Insufficient available Ledger balance for a credit | `declined` | `“NSF”` |

\* Default value; can be [customized](https://plaid.com/docs/transfer/transfer-rules/index.html.md#creating-additional-custom-rulesets) .

##### Debit transactions 

The following balance-based decisions are applicable for debits if you are not using [Signal](https://plaid.com/docs/signal/index.html.md) . If you are a [Signal](https://plaid.com/docs/signal/index.html.md) customer, the Transfer Risk Engine will instead use the results of your [Signal ruleset](https://plaid.com/docs/signal/signal-rules/index.html.md) .

Many of these rules can be [customized](https://plaid.com/docs/transfer/transfer-rules/index.html.md#creating-additional-custom-rulesets) through the Rules section of the Transfer Dashboard.

| Transfer Type | Scenario | Authorization Decision | Decision Rationale Code |
| --- | --- | --- | --- |
| Debit | Item was manually verified through Database Auth and result was `database_insights_pass_with_caution` | `approved`\* | `"MANUALLY_VERIFIED_ITEM"` |
| Debit | Account balance could not be verified due to an error fetching the balance | `approved`\* | `"ERROR"` |
| Debit | Account balance could not be verified because a credentials-based Item was disconnected. | `approved`\* | `"ITEM_LOGIN_REQUIRED"` |
| Debit | User account doesn't have sufficient balance to complete the debit transfer | `declined` | `"NSF"` |
| Debit | There are sufficient funds in the account balance for the transaction amount | `approved` | `null` |

\* Default value; can be [customized](https://plaid.com/docs/transfer/transfer-rules/index.html.md#configuring-balance-checks-in-the-transfer-risk-engine) .

The following decisions are applicable for debits only if you are a Signal customer:

| Transfer Type | Scenario | Authorization Decision | Decision Rationale Code |
| --- | --- | --- | --- |
| Debit | Signal rules were run and the transfer was identified as high risk due to the likelihood of insufficient funds, administrative returns, or unauthorized returns. | `declined` | `"RISK"` |

#### Testing Transfer rules in Sandbox 

The Transfer Rules Dashboard lets you switch between Sandbox and Production environments. You can create or edit Transfer rulesets in Sandbox mode just as you would in Production. To test rulesets you have created in Sandbox, make sure to pass the appropriate `ruleset_key` to your [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call while using the Sandbox environment.

*   To simulate the account having insufficient balance, you can either use [custom Sandbox users](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) to create a user with a specific balance, or simply attempt a transfer for a higher amount than the available balance in that account. You can verify the available balance by making a call to [/accounts/balance/get](https://plaid.com/docs/api/products/balance/index.html.md#accountsbalanceget) .
    
*   To simulate the Item going into an `ITEM_LOGIN_REQUIRED` state, call [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) , passing in that account's access token.
    
*   To simulate an Item that was verified through Database Auth, follow the instructions for [Testing Database Auth](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-auth-or-database-insights) in Sandbox.

---


# Transfer - Errors and returns | Plaid Docs

Errors and returns 
===================

#### Troubleshooting common errors and ACH returns 

#### Overview 

ACH returns and Transfer errors can both require investigation and troubleshooting.

An ACH return means that your attempted ACH transfer was returned. This typically not due to a Plaid issue and instead is caused by a problem with the ACH transfer itself, such as alleged fraud, insufficient funds, or a closed account. For more details, see [ACH Returns](https://plaid.com/docs/transfer/troubleshooting/index.html.md#ach-returns) .

A Transfer error is an error from the Plaid Transfer API. Transfer errors are related to your interaction with the Plaid API. Causes may include bank API downtime, exceeding Plaid's limits for transfer activity, or attempting to use a Plaid Transfer feature you haven't been enabled for. For more details, see [Transfer errors](https://plaid.com/docs/transfer/troubleshooting/index.html.md#transfer-errors) .

#### ACH returns 

After an ACH payment has been posted, it can be [returned](https://plaid.com/resources/ach/ach-return/) and clawed back from your account for a number of reasons. For example, a bank could determine that there are insufficient funds to complete the transfer, or a consumer can contact their bank and flag the transaction as unauthorized. If a debit transfer results in an ACH return, the funds will be automatically clawed back in a return sweep. If a credit transfer experiences an ACH return, the funds will be returned to your Ledger available balance.

Note that an ACH return is distinct from an ACH reversal. An ACH reversal is performed only to correct an erroneous transfer and will only be done at the request of the originator (i.e. you). For details, see [Escalating issues with ACH transfers](https://plaid.com/docs/transfer/troubleshooting/index.html.md#escalating-issues-with-ach-transfers) .

If an ACH transfer is returned, its status will be `returned`. All returned ACH transactions will have an ACH return code. By reading the code, you can troubleshoot returned transactions.

For more detailed troubleshooting information, see [Common ACH Return Codes in the Help Center](https://support.plaid.com/hc/en-us/articles/32881797799575-What-are-the-Common-ACH-Return-Codes) .

For a full list of ACH return codes, see [ACH Return Codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) .

| Return Code | Description | Notes | Troubleshooting |
| :-- | :-- | :-- | :-- |
| R01 | Insufficient funds | Available balance is not sufficient to cover the dollar amount of the debit entry. | If you are submitting the transfer on a Friday, we recommend using Same-Day ACH to decrease the likelihood of the user's account balance dipping below the transfer amount over the weekend. |
| R03 | No account or unable to locate account | The account number structure is valid, but the account number does not correspond to an existing account, or the name on the transaction does not match the name on the account. | Prompt the user to link another account via Plaid Link and use this newly linked account to create the transfer. |
| R09 | Uncollected funds | Available balance is sufficient, but the collected balance is not sufficient to cover the entry | Retry the transaction a few days later after any large "holds" on the user's account have been released. |
| R10 | Customer advises not authorized | Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document. | Make sure you add proper WEB debit authorization language to your "pay with bank" UX to protect against exposure of returns of over 60 days. Unlike other ACH return codes, you cannot resubmit a payment after encountering an R10 error. |

A returned transfer can be retried up to 2 times. When you try to reprocess a returned transfer, the `description` field in your [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) request must be `"Retry 1"` or `"Retry 2"` to indicate that it's a retry of a previously returned transfer. Note that retries are only allowed for transfers returned as R01 or R09.

##### ACH return categories 

ACH return rates are broken into three categories.

_Administrative_: The transfer could not be processed due to a technical error with the account. Common return codes in this category include R02 (account closed), R03 (no account), and R04 (invalid account number).

_Unauthorized_: The transfer was reported as unauthorized. Common return codes in this category include R10 (customer advises originator is not authorized to debit account), R11 (customer advises originator is authorized to debit account, but amount is incorrect), and R07 (customer advises authorization to debit account was revoked).

_Other_: All other returns. The most common code in this category is R01 (insufficient funds).

###### Return rate limits 

You can view your current return rates by category on the Transfer Dashboard. Plaid's maximum limits for ACH return rates are:

*   Overall: 12%
*   Administrative: 2.5%
*   Unauthorized: 0.4%

For more details, see [ACH Debit Return Rate Thresholds](https://support.plaid.com/hc/en-us/articles/32881513531671-What-are-my-obligations-as-an-ACH-Originator#h_01JYHCEY1RT625QMSVWQPDEVPB) .

If you exceed these limits in a 30 day period, you will be contacted by Plaid with a warning email. Failure to reduce return rates below these limits within three months may result in a fine. If excessive return rates remain unaddressed for an extended period of time, your access to Plaid Transfer may be revoked. If you are having trouble reducing your return rates below these limits, contact your Plaid Account Manager for help.

#### RTP failures 

Plaid performs various checks within [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) to fail upfront and as early as possible if the RTP or FedNow transfer won't succeed. However, due to the asynchronous nature of the RTP and FedNow payment networks, it is still possible for transfers to fail after authorization due to a rejection by the receiving bank or an issue in the payment network. Failures in the real-time networks are rare (<1%), and often indicate that the consumer bank account itself is in an unusable state.

If the RTP transfer failed, the status will be `failed` and an error code will be present in the `return_code` transfer property. For the following failure codes, further attempts to use this bank account for payouts via the real-time network are unlikely to succeed. Instead, we recommend that you prompt your user to link a different bank account via Plaid Link.

For a full list of RTP failure codes, see [RTP / RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) .

| Return Code | Description | Notes |
| :-- | :-- | :-- |
| AC03 | Creditor account is invalid | Account number is not recognized as valid by the receiving bank. |
| AC04 | Account closed | The account is closed and no longer active. |
| AC06 | Account is blocked | Receiving bank has placed a block on the account, for various operational or legal reasons. |
| E997 | Timeout clock has expired | The timeout for processing this transaction was exceeded in the FedNow network. You can safely retry the payment with a different idempotency key. |

#### Transfer errors 

For error codes specific to transfer and accompanying troubleshooting steps, including for common errors [TRANSFER\_NETWORK\_LIMIT\_EXCEEDED](https://plaid.com/docs/errors/transfer/index.html.md#transfer_network_limit_exceeded) , [TRANSFER\_ACCOUNT\_BLOCKED](https://plaid.com/docs/errors/transfer/index.html.md#transfer_account_blocked) , and [TRANSFER\_FORBIDDEN\_ACH\_CLASS](https://plaid.com/docs/errors/transfer/index.html.md#transfer_forbidden_ach_class) see [Transfer error codes](https://plaid.com/docs/errors/transfer/index.html.md) .

##### Handling 500 errors in transfer creation 

You may occasionally encounter a 500 HTTP error when creating a transfer via [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) or [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . In this case, it's possible that the authorization or transfer was created successfully, but the response was not received. It is highly recommended to use the `idempotency_key` field in [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) so that retries in this scenario are safe to perform and will not result in duplicate authorizations. Retrying [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) with the same `authorization_id` is guaranteed to only ever produce a single transfer.

Whether you retry the request to [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) or not, it's possible that the first request succeeded, and so your integration should be prepared to consume events from [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) that you may not have seen the `transfer_id` for previously. It is recommended you have a recovery process in place, either by logging these instances for manual review and reconciliation, or automatically reconciling by pulling the transfer details via [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) and using the `transfer.metadata` property to utilize any client-side data you attached to the transfer for reference.

Another way to determine if a transfer creation succeeded after receiving a 500 error from [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) is to follow up with a call to [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) using the `authorization_id` you received from [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . If the transfer was actually created, you will receive a successful response containing the transfer details. If it wasn't, you will receive a 404 HTTP error with the `NOT_FOUND` error code.

#### Escalating issues with ACH transfers 

In the event of a problem with an ACH transfer, you can escalate to Plaid. Typical reasons to request an escalation include:

*   You accidentally submitted an erroneous transfer
*   Your end-customer claims that they did not receive funds you sent them
*   Your end-customer claims that you made an unauthorized debit from their account

Available escalation types include reversals, recalls, trace requests, and written statement of unauthorized debit (WSUD) requests.

To learn more about escalations, including which escalation type is appropriate for your situation and how to submit an escalation, see [How are ACH Transfer Investigations Escalated?](https://support.plaid.com/hc/en-us/articles/32881719199767-How-are-ACH-Transfer-Investigations-Escalated)

---


# Transfer - Transfer UI | Plaid Docs

Receiving Funds Using Transfer UI 
==================================

#### Facilitate transfers with an intuitive user interface 

Plaid Transfer UI is a drop-in user interface that makes it easy for end users to authorize one-time transfers. Transfer UI is compliant with Nacha WEB guidelines and automatically captures and manages [Proof of Authorization](https://plaid.com/docs/transfer/creating-transfers/index.html.md#managing-proof-of-authorization) on your behalf.

If your use case involves one-time debit transfers and you do not have the resources to build your own authorization UX, Transfer UI may be a good fit for you.

With Transfer UI, users are able to authorize payments or disbursements. (While Proof of Authorization requirements are not mandatory for credits, Transfer UI supports both credit and debit transfers.) Before authorizing a transfer, users are able to review transfer details, such as amount, fund origination account, fund target account, and more.

Transfer UI does not currently support [recurring transfers](https://plaid.com/docs/transfer/recurring-transfers/index.html.md) , [Database Auth](https://plaid.com/docs/auth/coverage/database/index.html.md) , or [Platform Payments](https://plaid.com/docs/transfer/platform-payments/index.html.md) . Transfer UI cannot be used to capture standing authorizations such as those required for variable recurring payments.

(An image of "Mobile app transfer UI flow showing loan payment process, payment method selection, transfer confirmation, and success message.")

Example Transfer UI flow.

[Prefer to learn by watching? Get an overview of how Transfer UI works in just 3 minutes!](https://www.youtube.com/watch?v=BlwZKTIpHJk)

#### Integration 

To integrate with Transfer UI, follow the following steps:

1.  In the Plaid Dashboard, create a [Link customization](https://plaid.com/docs/link/customization/index.html.md) with "Account Select" set to the "Enabled for one account" selection.
    
2.  Call [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) to obtain a `transfer_intent.id`.
    
3.  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , specifying `["transfer"]` in the `products` parameter, the `transfer_intent.id` in the `transfer.intent_id` parameter, and the name of your Link customization in the `link_customization_name` parameter. If you already have an `access_token` for this user, you can provide it to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to streamline the Link flow, otherwise, the user will authenticate their bank account within the same Transfer UI session.
    
4.  Initialize a Link instance using the `link_token` created in the previous step. For more details for your specific platform, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
    
5.  The user will now go through the Link flow to perform their transfer. The `onSuccess` callback will indicate they have completed the Link flow.
    
6.  (Optional) You will receive a `public_token` from the `onSuccess` callback. If you do not already have an access token for this user's account, call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange this public token for an `access_token` in order to streamline future transfers for this user.
    

#### Transfer UI user flows 

Depending on whether you provided an access token in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) step, the Transfer UI experience will differ.

Bank on file flow (`access_token` provided):

(An image of "Plaid transfer UI flow: 1. Sending credentials. 2. Confirm transfer from Bank to customer. 3. Transfer success.")

Example Transfer UI flow if the access\_token is provided.

Net new user flow (`access_token` not provided):

(An image of "6-step UI flow for Plaid transfer without access\_token: connecting account, selecting bank, entering credentials, account selection, transfer confirmation, success.")

Example Transfer UI flow if the access\_token is not provided.

#### Tracking transfer creation 

The instructions in this section correspond to the Web and Webview libraries for Link. If you're using a mobile SDK, information about the transfer intent status can be found in the `metadataJson` field in the SDK's `onSuccess` callback. As an example, see [Android: metadataJson](https://plaid.com/docs/link/android/index.html.md#link-android-onsuccess-metadata-metadataJson) .

You can determine whether a transfer was successfully created by referring to the `transfer_status` field in the `metadata` object returned by `onSuccess`. A value of `complete` indicates that the transfer was successfully originated. A value of `incomplete` indicates that the transfer was not originated. Note that this field only indicates the status of a transfer creation. It does not indicate the status of a transfer (i.e., funds movement). For more information on transfer intents, see [Retrieving additional information about transfer intents](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#retrieving-additional-information-about-transfer-intents) . For help troubleshooting incomplete transfers, see [Troubleshooting Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#troubleshooting-transfer-ui) .

When using Transfer UI, the `onSuccess` callback is called at a different point in time in the Link flow. Typically, the `onSuccess` callback is called after an account is successfully linked using Link. When using Transfer UI, however, the `onSuccess` callback is called only after both of the following conditions are met: an account is successfully linked using Link and a transfer is confirmed via the UI. Note that the `onSuccess` callback only indicates that an account was successfully linked. It does not indicate a successful transfer (i.e., funds movement).

```bash
{
  institution: {
    name: 'Wells Fargo',
    institution_id: 'ins_4'
  },
  accounts: [
    {
      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
      name: 'Plaid Checking',
      mask: '0000',
      type: 'depository',
      subtype: 'checking',
      verification_status: ''
    },
    {
      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
      name: 'Plaid Saving',
      mask: '1111',
      type: 'depository',
      subtype: 'savings'
    }
    ...
  ],
  transfer_status: 'incomplete',
  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
}
```

#### Retrieving additional information about transfer intents 

To retrieve more information about a transfer intent, call the [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) endpoint and pass in a transfer intent `id` (returned by the [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) endpoint).

```javascript
const request: TransferIntentGetRequest = {
  transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
};


try {
  const response = await client.transferIntentGet(request);
} catch (error) {
  // handle error
}
```

```json
{
  "transfer_intent": {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "ach_class": "ppd",
    "amount": "15.75",
    "authorization_decision": "APPROVED",
    "authorization_decision_rationale": null,
    "created": "2020-08-06T17:27:15Z",
    "description": "Desc",
    "failure_reason": null,
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "mode": "DISBURSEMENT",
    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
    "status": "SUCCEEDED",
    "transfer_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "user": {
      "address": {
        "street": "100 Market Street",
        "city": "San Francisco",
        "region": "California",
        "postal_code": "94103",
        "country": "US"
      },
      "email_address": "lknope@email.com",
      "legal_name": "Leslie Knope",
      "phone_number": "123-456-7890"
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}
```

The response is a `transfer_intent` object with more information about the transfer intent.

The `status` field in the response indicates whether the transfer intent was successfully captured. It can have one of the following values: `FAILED`, `SUCCEEDED`, or `PENDING`.

If the value of `status` is `FAILED`, the transfer intent was not captured. The `transfer_id` field will be `"null"` and the `failure_reason` object will contain information about why the transfer intent failed. Some possible reasons may include: the authorization was declined, the account is blocked, or the origination account was invalid.

If the value of `status` is `SUCCEEDED`, the transfer intent was successfully captured. The accompanying `transfer_id` field in the response will be set to the ID of the originated transfer. This ID can be used with other [Transfer API endpoints](https://plaid.com/docs/api/products/transfer/index.html.md) .

A value of `PENDING` can mean one of the following:

*   The transfer intent has not yet been processed by the authorization engine (`authorization_decision` is `"null"`). This is the initial state of all transfer intents.
    
*   The transfer intent was processed and approved by the authorization engine (`authorization_decision` is `"approved"`), but has not yet been processed by the transfer creation processor.
    
*   The transfer intent was processed by the authorization engine and was declined (`authorization_decision` is `"declined"`) due to insufficient funds (`authorization_decision_rationale.code` is `"NSF"`). If this is the case, the end user can retry the transfer intent up to three times. The transfer intent status will remain as `"PENDING"` throughout the retry intents. After three unsuccessful retries, the transfer intent status will be `"FAILED"`.
    

#### Transfer UI best practices 

While transfer UI provides a Nacha-compliant UI for your transfers, to maximize conversion, it is recommended to still provide context in your own app to your end users about the transfer. We recommend that your app implement a UI where the customer selects or confirms the transfer amount and, if applicable, the funds source or destination. To maximize user confidence, your app should also provide a post-Link success pane confirming the transfer details, including amount and effective date.

#### Sample implementation 

For a real-life example of an app that incorporates both Transfer and Transfer UI, see the Node-based [Plaid Pattern Transfer](https://github.com/plaid/pattern-transfers) sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers.

#### Troubleshooting Transfer UI 

##### The onExit callback is called 

If the `onExit` callback is called, the Link session failed to link an account. The transfer intent could not be initiated.

##### onSuccess is called, but the transfer intent is incomplete 

The `onSuccess` callback is not an indication of a successful transfer creation or a successful transfer (i.e., funds movement). It only indicates the successful linking of an account. To fully diagnose incomplete transfer intents (i.e., when the `transfer_status` field in the `metadata` object returned by `onSuccess` is `incomplete`), call the [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) endpoint and pass in the corresponding transfer intent ID as an argument. Information about the transfer intent can be found in the `status`, `failure_reason`, `authorization_decision`, and `authorization_decision_rationale` fields in the response.

##### Network errors or institution connection issues 

Network errors or institution connection issues can also result in incomplete transfer intents. In such cases, generate a new Link token using the existing `access_token` and invoke Transfer UI to allow the end user to attempt the transfer intent again.

---


# Credit and Underwriting | Plaid Docs

Underwriting products 
======================

#### Review and compare underwriting solutions 

This page provides overviews of Plaid's underwriting and lending products to help you find the right one for your needs.

#### Consumer Report by Plaid Check 

[Plaid Check](https://plaid.com/docs/check/index.html.md) products include scores and analyses that you can use directly for underwriting purposes, along with transaction data categorized into lender-relevant categories. The Consumer Report provides raw data similar to Assets, with additional analysis such as overall inflow and outflow counts and averages. Consumer Report is enhanced by two optional add-ons: Income Insights and Partner Insights. Income Insights provides historical monthly and annual gross income data as well as future income predictions. Partner Insights provides pre-generated cashflow underwriting risk scores and analysis in partnership with Prism Data.

Consumer Report also provides an optional Verification of Assets (VOA) feature, a FCRA-compliant and Fannie Mae Day 1 Certainty-approved report that delivers a comprehensive view of a borrower's assets, tailored for mortgage lenders. VOA is currently in early availability; for more details, [contact Sales](https://plaid.com/check/consumer-report/#contact-form) .

Plaid Check can be used together with most Plaid Inc. products, such as Layer or Balance, but cannot be used with Assets or Income.

[See a live, interactive demo](https://plaid.coastdemo.com/share/67ed96db47d17b02bdfc4a88?zoom=100) of a Plaid-powered underwriting flow, using Consumer Report by Plaid Check.

#### Assets 

[Assets](https://plaid.com/docs/assets/index.html.md) gets details on an end user's assets and balances, including transaction history, with inflows and outflows categorized into lender-relevant categories. Asset reports can be provided either in JSON format for programmatic use or PDF format for human-powered verification workflows. Assets is optimized for verification and underwriting for traditional loan origination.

#### Income 

[Income](https://plaid.com/docs/income/index.html.md) gets income details suitable for cash flow underwriting and income or employment verification. Where Assets provides all transactions and requires you to analyze them yourself, Income identifies specific income streams and provides details such as amount and frequency. Income supports both gig and payroll income types and can verify income based on deposits to a linked account (Bank Income), user-uploaded documentation such as W-2s or pay stubs (Document Income), or data imported from a linked payroll provider (Payroll Income).

[See a live, interactive demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100) of a Plaid-powered underwriting flow, using Assets and Income.

#### Consumer Report, Assets, and Income comparison 

Consumer Report by Plaid Check is recommended for most new customers. Assets and Income may be appropriate for customers who have use cases that aren't supported by Plaid Check, such as supporting non-US-based customers. Assets and Income can't be used together in the same Link flow with Consumer Report by Plaid Check.

Assets provides a broader financial picture as part of traditional loan underwriting and asset verification, while Income focuses on providing rich income data optimized for cash flow underwriting and employment verification and supports a variety of data sources.

Consumer Report by Plaid Check provides data similar to Assets and Income, plus risk scoring and income insights. With its off-the-shelf insights, Consumer Report is ideal for customers who want to do cash flow underwriting without building their own credit risk attributes and scores from raw bank transaction data. When used with the optional asset verification feature, it's also the best solution for mortgage underwriting.

|  | Assets | Income | Consumer Report by Plaid Check |
| --- | --- | --- | --- |
| Summary | Provides financial data for underwriting decisions and asset verification | Provides analyzed and parsed income streams for cash flow underwriting decisions and income/employment verification | Provides financial data for underwriting decisions, asset verification, and cash flow underwriting, plus underwriting risk analysis and optional Verification of Assets for mortgage underwriting |
| Provides detailed balance and transaction history that can be used for underwriting purposes | Yes | Income transactions only | Yes |
| Provides off-the-shelf risk scores for cash flow underwriting | No | No | Yes, with Partner Insights |
| Identifies income streams and provides historical income dates and amounts | No | Yes | Yes, with Income Insights |
| Provides future income predictions and historical income summaries | No | No | Yes, with Income Insights |
| Provides reports in either PDF or JSON format | Yes | Yes | Yes |
| Day 1 Certainty report provider for Fannie Mae Desktop Underwriting | Yes | No | Yes |
| Provides identity data from linked financial institution accounts to reduce fraud risk | Yes | Yes, with Bank Income | Yes |
| Supports data from linked financial institution accounts | Yes | Yes, with Bank Income | Yes |
| Supports data from payroll providers | No | Yes, with Payroll Income | No |
| Supports data from user-uploaded documents | No | Yes, with Document Income | No |
| Can be used in a single Link session with other Plaid products such as Auth | Yes | Yes, with Bank Income | No |
| Supported countries | US, CA, UK, Europe | US, CA, UK | US |
| Billing plans available | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | 12-month contract (Custom only) |

#### Statements 

[Statements](https://plaid.com/docs/statements/index.html.md) (US only) gets exact copies of PDF statements as provided by the financial institution, to streamline your verification processes that require statement copies. Because Statements does not cover all major or long-tail institutions, it should be used with a fallback option in place if data is not available. Statements supports only depository (e.g. checking, savings, or money market) accounts.

---


# Authentication | Plaid Docs

Authentication 
===============

#### Building Plaid Exchange OAuth 

Overview 
---------

This section will help you prepare your OAuth 2.0 provider for connecting to Plaid.

### Prepare your OAuth 2.0 server 

If you are using your existing OAuth identity provider. (For example, Okta, Auth0, Ping Identity, Azure Active Directory, AWS Cognito), please prepare all the URLs and settings required for access. This include firewall rules, scopes and audiences. Initially have these URLs ready:

| End Point | Description |
| --- | --- |
| `authorization_endpoint` | Your OAuth landing page, where users can sign in and generate a `code` for Plaid |
| `token_endpoint` | The token exchange endpoint where Plaid can use the `code` to generate an `id_token`, `access_token` and `refresh_token` |

If you don't yet have an identity provider, Plaid recommends [our partner, Okta](https://www.okta.com/blog/2023/02/how-oktas-new-plaid-integration-keeps-your-banking-secure/) . Okta is an industry-leading, independent provider with expertise onboarding data partners to OAuth integrations. [Contact us](https://plaid.commailto:dataconnectivity@plaid.com) for help getting started with Okta.

If these are not options, there is the option of building a net new provider to support Plaid Exchange.

Note: OIDC Discovery (Well Known Config) and JWKS are not supported in Plaid Exchange

##### Issue Plaid a client ID and client secret 

In order to allow Plaid to authenticate its request for an access token, you will need to issue a client ID and client secret. You may create the client ID and client secret using your preferred method, but we provide some guidance [in this guide](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-id-and-client-secret) . Once you have created a client ID and client secret, provide them to your Plaid contact.

##### Authorization flow overview 

Once you have a server and have issued Plaid a client ID and client secret, the authorization flow occurs as follows:

1.  Plaid redirects the end user to your [authorization\_endpoint](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#plaid-redirects-the-end-user) .
2.  The user completes all authentication steps and you generate an [authorization code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#you-give-plaid-an-authorization-code) .
3.  Plaid uses the authorization code to request an [access token](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#token-flow) .
4.  Plaid uses the access token to identify the user (unique consistency key).

(This described authentication flow conforms to commonly implemented patterns for the [OIDC spec](https://openid.net/specs/) . Plaid welcomes partner [feedback](https://plaid.commailto:dataconnectivity@plaid.com) .)

##### Client ID and client secret 

In order to register an application for your server, you will need to create a client ID and client secret. These will be shared with Plaid so that the Plaid can identify itself. Below, you will find best practices and code samples to help you create a [client ID](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-id) and [client secret](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-secret) .

##### Client ID 

A client ID is a public identifier that you assign to Plaid. While it is not secret, we recommend choosing a client ID that is not easy to guess.

##### How to create a client ID 

One way to create a client ID is to use a random 32-character hex string. See the code samples below:

```javascript
require('crypto').randomBytes(16).toString('hex');
```

\=\*=\*=\*=

#### Client secret 

The client secret is essentially a password that you assign to Plaid. In order to keep it secure, please follow these [best practices](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) :

*   Generate the client secret in a way that makes it impossible to guess or backwards-generate. (For example, do not use a UUID as many common libraries take into account the timestamp or MAC address of the generating server).
*   Never store the client secret in plain text—always keep it encrypted or hashed.
*   Make the client secret visually different from the client ID. (This reduces the risk of a user copy/paste error when handling the client ID and client secret).

\=\*=\*=\*=

#### How to generate a client secret 

One way to securely generate a client secret is to follow the steps below:

1.  Create a 256-bit value using a cryptographically secure pseudo random number generator (CSPRNG).
2.  Convert the value from step 1 to a hexadecimal representation.

See the code samples below:

```javascript
require('crypto').randomBytes(32).toString('hex');
```

Authorization flow 
-------------------

\=\*=\*=\*=

#### Plaid redirects the end user 

When your user first initiates the process of linking their account, Plaid redirects their browser to the `authorization_endpoint`. Plaid's redirect includes these query parameters:

| Query parameter | Value | Description |
| --- | --- | --- |
| `response_type` | `code` | The type of response Plaid expects. |
| `redirect_uri` | `https://cdn.plaid.com/link/v2/stable/oauth.html` | Where Plaid expects your organization to redirect back to once the user completed all authentication steps. |
| `client_id` | A [client ID](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-id-and-client-secret) | The [client ID](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-id-and-client-secret) you issued to Plaid. |
| `state` | An opaque string | Plaid generates this. Your organization will return the same string when redirecting to the `redirect_uri`. |
| `institution_id` | ID representing the data partner/FI | This is a Plaid assigned ID that represents your organization |
| `application_id` | ID representing the requesting application | A Plaid assigned ID that represent the application requesting access. Can be used in combination with Permissions Management. |
| `scope` | (OPTIONAL) Set of scope string: `http://plaid.test` | The set of scopes Plaid requests access to. |
| `audience` | (OPTIONAL) Set of audience strings: `openid offline_access customScope` | The set of audiences Plaid requests access to. |
| `code_challenge` | (OPTIONAL) Challenge string | Provides the code assigned to Plaid to start PKCE flow. Generated with `code_verifier` |
| `code_challenge_method` | (OPTIONAL) Defines the PKCE method :`S256` | Provides the PKCE method. |

Optional fields can be requested, please contact Plaid to learn more.

\=\*=\*=\*=

#### Example 

Plaid's redirect:

```bash
https://auth.firstplatypus.com/oauth2/v1/authorize?response_type=code&redirect_uri=https%3A%2F%2Fcdn.plaid.com%2Flink%2Fv2%2Fstable%2Foauth.html&scope=openid%20offline_access&client_id=c5a5245b062bf8420d11ab4361b28a15&state=eyJvYXV0aF9zdGF0ZV
```

This page will be requested directly by the user's device. Your authorization endpoint must support TLS and be publicly accessible. Control of user authentication has now been handed off to you. A typical authentication flow will include a username and password submission form and a 2FA step. For partners with native mobile applications, Plaid strongly recommends enabling support for [App2App](https://openid.net/tag/app2app/) and using [biometric authentication](https://webauthn.guide/) to improve the user's authentication experience.

\=\*=\*=\*=

#### You give Plaid an authorization code 

After the user completes all required authentication steps, your organization generates a temporary authorization code and redirects the user's browser back to the `redirect_uri`. The following query parameters must be included with the request:

| Query parameter | Description |
| --- | --- |
| `code` | The temporary authorization code. Plaid exchanges this for an access token in the [next step](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#token-flow) . |
| `state` | The `state` parameter from the [previous step](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#plaid-redirects-the-end-user) . Plaid verifies that the two values match. |

\=\*=\*=\*=

#### Auth Example 

Your response:

```bash
https://cdn.plaid.com/link/v2/stable/oauth.html?code=1284918391&state=eyJvYXV0aF9zdGF0ZV
```

If a user does not complete all the required steps (for example, if they choose to cancel rather than authorize) you should handle it as an error. See the [error handling](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#error-handling) section for more information.

Token Flow 
-----------

Plaid sends a request to your `token_endpoint`. Unlike the two previous steps, the request to `token_endpoint` is a backend-to-backend call and must be authenticated. The authentication credentials consist of the [client ID and client secret](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-id-and-client-secret) you issued to Plaid. The authentication method will be one of the [authentication methods](https://plaid.comhttps://developer.okta.com/docs/reference/api/oidc/index.html.md#client-authentication-methods) specified in your [well-known configuration](https://plaid.comhttps://developer.okta.com/docs/reference/api/oidc/index.html.md#well-known-openid-configuration) .

For example, if the authentication method is set to `client_secret_basic`, Plaid will include a [basic authentication](https://plaid.comhttps://developer.okta.com/docs/reference/api/oidc/index.html.md#request-example-access-token-using-client-secret-basic-client-authentication) header in its request.

Plaid will also send the authorization code (`code`) in the body of the request and expects to receive an `access_token`, `id_token`, and `refresh_token` in your response.

\=\*=\*=\*=

#### Body parameters 

| Body parameter | Value | Comment |
| --- | --- | --- |
| `grant_type` | `authorization_code` | The type of grant Plaid is exchanging for an access token. (In this case, an authorization code.) |
| `redirect_uri` | `https://cdn.plaid.com/link/v2/stable/oauth.html` | Where Plaid expects your organization to redirect back to once the user completed all authentication steps. |
| `code` | The `code` you sent to Plaid in the [previous step](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#you-give-plaid-an-authorization-code) | The temporary authorization code Plaid is exchanging for the access token. |
| `code_verifier` | (OPTIONAL) `code` used to generate challenge | A code provided to Plaid or generated by Plaid to use as the key for PKCE challenge codes |

\=\*=\*=\*=

#### Token request example 

Plaid's request:

```bash
curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
--header 'Content-Type: application/json' \
--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs"
--data-raw '{
    "grant_type": "authorization_code",
    "code": "1284918391",
    "redirect_url": "https://cdn.plaid.com/link/v2/stable/oauth.html"
}'
```

\=\*=\*=\*=

#### Response parameters 

Your organization validates that the `client_id`, `client_secret`, `code` and `redirect_uri` parameters from Plaid's request all match the expected values. Your response to this request contains everything that Plaid needs to later access your Plaid Exchange API:

| Property | Description |
| --- | --- |
| `access_token` | An opaque string (likely a JWT structured according to the [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc9068#section-2.2) ). Plaid will present this string as a bearer token to all requests made to your Plaid Exchange API. This encodes the identity of the user and the scope of access granted. |
| `id_token` | An [OIDC ID token](https://openid.net/specs/openid-connect-Plaid-1_0.html#IDToken) . Plaid only reads the `sub` field from this token.  
In a deployment with multiple financial institutions, the `sub` field must be unique to each financial institution. (It doesn't need to be unique to the user across all financial institutions.) |
| `refresh_token` | An opaque string (likely a JWT) that can be used to request a new access token. Plaid will use this to fetch data periodically long after the original access token expires. See the [refresh flow](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#refresh-flow) section for more information.  
Plaid doesn't recommend setting an inactivity timeout for the refresh token because it's not a good indicator of whether a user is active with a Plaid partner. For example, some Plaid partners can trigger Plaid to call the Plaid Exchange endpoint `/accounts/{accountID}` infrequently for large transactions. |
| `user_id` | (Optional if `id_token` is not possible) A unique identifier that replaces the `id_token.sub` |

\=\*=\*=\*=

#### Token response example 

Your response:

```json
{
  "access_token": "agstynmdygjdghabrgraeh...",
  "id_token": "snsyjrhvjdtvyjvsgcegaethstj...",
  "user_id": "2347456437346745", // Optional, see above
  "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}
```

If `user_id` and `id_token` are not present, the final attempt to resolve the unique consistency key will be via the FDX endpoint called `/customer/current`. The response is listed below.

```json
{
  "customerId": "2347456437346745"
}
```

After it receives this response, Plaid has everything it needs to access your Plaid Exchange API.

Refresh flow 
-------------

For some use cases, Plaid needs to periodically fetch fresh data on behalf of the user. To get a new access token, Plaid makes another request to your `token_endpoint` with a different set of parameters.

\=\*=\*=\*=

#### Body parameters 

| Body parameter | Value | Description |
| --- | --- | --- |
| `grant_type` | `refresh_token` | Specifies that Plaid is requesting a new access token to replace the expired access token. |
| `refresh_token` | Example: `dhcsrtjsrgayvkdisfdgntshstu...` | The refresh token you issued to Plaid.  
  
**Note:** Plaid recommends setting the expiration at 13 months. This allows you to avoid running into expiration issues during time-sensitive intervals (for example, on tax day). |

\=\*=\*=\*=

#### Refresh example 

Plaid's request:

```bash
curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
--user "plaid:rVXYOoQS4rHUG79n_48al"
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "refresh_token",
    "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}'
```

Your response:

```json
{
  "access_token": "lngarogglkcangasgabba...",
  "expires_in": 900,
  "id_token": "snsyjrhvjdtvyjvsgcegaethstj..."
}
```

See the [previous section](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#response-parameters) for descriptions of these response parameters.

Error handling 
---------------

How to [handle an error](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1) that occurs during the [authorization flow](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#authorization-flow) .

\=\*=\*=\*=

#### Incorrect redirect URI 

If the request fails due to an incorrect, missing, invalid, or mismatched `redirect_uri`, notify Plaid of the error and do not redirect the user to the `redirect_uri`. We recommend displaying an error page to notify the user that an error has occurred.

\=\*=\*=\*=

#### User cancellation 

If the user cancels the request or if the request fails for any other reason other than an incorrect URI, include the following required query parameters with the request. (Please see the [OAuth spec](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1) for a complete list of possible parameters.)

| Query parameter | Description |
| --- | --- |
| `error` | The reason for the error. See the [Errors](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#errors) table below for a list of possible errors. |
| `state` | The opaque string Plaid passed as the `state` parameter in the `authorization_endpoint` redirect step. |

\=\*=\*=\*=

#### Errors 

See the table below for a full list of possible errors, as defined in the [OAuth spec](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1) .

| Parameter | Description |
| --- | --- |
| `invalid_request` | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
| `unauthorized_client` | The client is not authorized to request an authorization code using this method. |
| `access_denied` | The resource owner or authorization server denied the request. |
| `unsupported_response_type` | The authorization server does not support obtaining an authorization code using this method. |
| `invalid_scope` | The requested scope is invalid, unknown, or malformed. |
| `server_error` | The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.) |
| `temporarily_unavailable` | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code can't be returned to the client via an HTTP redirect.) |

\=\*=\*=\*=

#### Example 

Your response:

```bash
https://cdn.plaid.com/link/v2/stable/oauth.html?error=access_denied&state=eyJvYXV0aF9zdGF0ZV
```

Alternative auth methods 
-------------------------

Plaid provides legacy support for existing integrations using non-OAuth authentication methods. However, these methods are deprecated, and new PX integrations must use OAuth for authentication.

[OAuth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md) is the preferred security method. However there are many existing integrations using the MFA/OTP options for authenticating a user. Plaid will continue to support these methods, but they are deprecated for new users.

Please work with Plaid if you have a limitation to OAuth and must use OTP or MFA.

This API reference describes the following alternative security endpoints with the following workflow:

1.  [POST /users/auth\_token](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#request-an-auth-token-for-a-user) : this endpoint is used for basic as well as multi-factor authentication.
    
    *   For basic, it returns an authorization response with an auth token for the user.
    *   For multifactor authentication flows, the endpoint responds with one of the following:
        *   [OTP challenge response](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#202-response-for-otp)
        *   [KBA challenge response](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#202-response-for-kba)
        *   [TOTP challenge response](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#202-response-for-totp)
2.  Based on the multifactor challenge type, Plaid then calls one or both of the following:
    
    *   [POST /users/{user\_id}/sendOtp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#trigger-otp) : Plaid sends this for `OTP` flows only.
    *   [POST /users/{user\_id}/2fa](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) For this endpoint, depending on the multi-factor authentication flow, Plaid sends one of the following:
        *   [OTP validation request](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-totp-or-otp) : For `OTP` or `TOTP`.
        *   [KBA validation request](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-kba) : For `KBA`. If the validation is successful, this endpoint returns an authorization response with an auth token for the user.

\=\*=\*=\*=

#### Request an auth token for a user 

Plaid uses the `POST /users/auth_token` endpoint to request an auth token for a user. This endpoint is the essential API method for authenticating user credentials and is a part of all non-OAuth authentication flows documented here, including multifactor flows.

*   For an overview of the basic flow of this endpoint, see [Alternative auth methods](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#alternative-auth-methods) .
*   For an example request and response, see the following section:

#### POST /users/auth\_token 

Provides Plaid a mechanism by which a credentials pair can be authenticated and exchanged for a user ID and access token authorized to request user-specific resources on behalf of the partner institution’s customer. This call may result in a 2-factor challenge.

**Request fields**

[username](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-auth_token-request-username)

required, string

Submitted username.

[password](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-auth_token-request-password)

required, string

Submitted password.

[institution\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-auth_token-request-institution-id)

string

Institution identifier for partners with multiple institutions.

```bash
curl  --location --request POST
'https://your-institution.com/users/auth_token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-PLAID-CLIENT-ID: example_ID' \
--header 'X-PLAID-SECRET: example_secret' \
--header 'X-PLAID-VERSION: 2021-03-26' \
--header 'Accept: application/json' \
--data-urlencode 'username=user123&password=pass123&institution_id=inst123'
```

##### Responses 

Successful responses include `200` for basic authentication and `202` for multifactor authentication.

##### 200 OK 

For basic authentication, `POST users/auth_token` returns a 200 response with the access token:

**Response fields** and example

[user\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-auth_token-response-user-id)

required, string

Opaque user identifier.

[auth\_token](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-auth_token-response-auth-token)

required, string

Opaque, revocable token.

```json
{
  "user_id": "YRQ8PPaohJ",
  "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"
}
```

###### 202 Accepted 

For more information, see the following [multifactor authentication section](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#multifactor-authentication) .

###### 400 Bad Request 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

###### 401 Not Authorized 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

###### 403 Forbidden 

The user’s account is locked, typically due to excessive incorrect authentication attempts. This response will trigger messaging to the user indicating that the account has been temporarily locked and will advise the user to contact the institution.

###### 405 Not Allowed 

This response should be used to indicate that the user’s account is not permitted to participate in aggregation, typically because the user must accept a license or terms of use. This will trigger messaging to the user indicating that the account is not yet authorized for online use and will direct the user to visit the partner institution’s online portal for further guidance. Plaid recommends that whatever pending terms or agreements that block this use case be presented to the user immediately upon login.

###### 503 

Signifying the institution is currently unavailable to respond to the request.

**Properties**

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error)

required, object

Generic error object.

[retry\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-retry-at)

string

The time, in UTC, when the institution is expected to support aggregation again.  
  

Format: `date-time`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

\=\*=\*=\*=

#### Multifactor authentication 

If the response from `POST /users/auth_token` is `202 Accepted`, then Plaid must challenge the user with a multifactor authentication flow.

The 202 response indicates that presented credentials are accepted for further processing. It does not indicate that the presented credentials are correct. For an overview of the multifactor authentication flow, see [Alternative auth methods](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#alternative-auth-methods) .

The 202 response body is one of the following:

*   `MfaOtpEscalationChallenge` for temporary, out-of-band password 2FA authentication. This indicates Plaid next requests [POST /users/{user\_id}/sendOtp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#trigger-otp) then [POST /users/{user\_id}/2fa](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) .
*   `MfaKbaEscalationChallenge` for knowledge-based 2FA authentication. This indicates Plaid next requests [POST /users/{user\_id}/2fa](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) .
*   `MfaTotpEscalationChallenge` for temporary, on-hand password 2FA authentication. This indicates Plaid next requests [POST /users/{user\_id}/2fa](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) .

See the following sections for details.

\=\*=\*=\*=

#### 202 response for OTP 

If Plaid receives the `MfaOtpEscalationChallenge` response (the most common scenario) from `POST /users/auth_token`, Plaid:

1.  Prompts the user in Plaid Link to select how they want their OTP sent, displaying the methods the partner indicates it supports in the `MfaOtpEscalationChallenge` response. For example, `voice` or `sms`.
2.  Sends the `POST /users/{user_id}/sendOtp` request indicating the partner should send the OTP to the user's selected method. For more information see [Trigger OTP API method](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#trigger-otp) .
3.  After receiving a 200 response, prompts the user in Plaid Link to fill in the OTP and waits for them to fill it in.
4.  Sends the OTP the user entered for validation using the `POST /users/{user_id}/2fa` request. For more information see [Validate 2FA](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) .

##### MfaOtpEscalationChallenge response 

Prompts user to choose how to receive their out-of-band one-time passcode as part of an MFA escalation

**Properties**

[user\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-user-id)

required, string

Opaque user identifier.

[challenge](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge)

required, object

Contains the prompt and send methods for the OTP.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-id)

Unique identifier for this escalation flow instance. Enables correlation of challenges with responses, preventing attackers from gaining leverage by spamming.

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-type)

Type of MFA escalation.

[fido2](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-type-fido2)

string

Cryptographic authenticator, via FIDO2.

[otp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-type-otp)

string

One-time passcode. The partner delivers this out of band from this API, for example through email or voice.

[kba](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-type-kba)

string

Knowledge-based authentication, question/response-based challenge method.

[push](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-type-push)

string

Coordinated push notification, requiring acknowledgement.

[totp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-type-totp)

string

Time-based one-time passcode. The user accesses this code through on-hand devices, for example, an authenticator app that displays a new passcode every 60 seconds.

[prompt](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-prompt)

string

The text prompting users for the passcode. Plaid will relay the user's locale using the Accept-Language header. If the partner doesn't provide this text, Plaid falls back to its own prompt wording.

[send\_methods](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-send-methods)

\[object\]

For OTP flows, a list of delivery descriptions for out-of-band delivery of the passcode.  
  

Min items: `1`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-send-methods-id)

string

An ID uniquely referencing this send method, for this user.

[mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-send-methods-mask)

string

A display-safe string that is evocative of this send method. An attacker should not gain an advantage if given this mask.

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaOtpEscalationChallengeResponse-challenge-send-methods-type)

string

Indicates the method of delivery.  
  

Possible values: `sms`, `email`, `voice`

```json
{
  "user_id": "example_id_string",
  "challenge": {
    "id": "example_id_string",
    "type": "otp",
    "send_methods": [
      {
        "id": "Z9D0iK",
        "mask": "(***) ***-8653",
        "type": "sms"
      },
      {
        "id": "36b4Xo",
        "mask": "j****@p****.com",
        "type": "email"
      }
    ]
  }
}
```

\=\*=\*=\*=

#### 202 response for KBA 

If Plaid receives the `MfaKbaEscalationChallenge` response from `POST /users/auth_token`, Plaid:

1.  Prompts the user in Plaid Link to enter answers to the questions that Plaid received in the `MfaKbaEscalationChallenge` response.
2.  Sends the answers the user entered for validation using the `POST /users/{user_id}/2fa` request. For more information see [Validate 2FA](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) .

##### MfaKbaEscalationChallenge response 

Questions the user must answer.

**Properties**

[user\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-user-id)

required, string

Opaque user identifier.

[challenge](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge)

required, object

Contains knowledge-based challenge questions.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-id)

Unique identifier for this escalation flow instance. Enables correlation of challenges with responses, preventing attackers from gaining leverage by spamming.

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-type)

Type of MFA escalation.

[fido2](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-type-fido2)

string

Cryptographic authenticator, via FIDO2.

[otp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-type-otp)

string

One-time passcode. The partner delivers this out of band from this API, for example through email or voice.

[kba](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-type-kba)

string

Knowledge-based authentication, question/response-based challenge method.

[push](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-type-push)

string

Coordinated push notification, requiring acknowledgement.

[totp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-type-totp)

string

Time-based one-time passcode. The user accesses this code through on-hand devices, for example, an authenticator app that displays a new passcode every 60 seconds.

[questions](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-questions)

\[object\]

The set of challenge questions.  
  

Min items: `1`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-questions-id)

string

Unique identified for this question. Enables correlation of questions with submitted responses.

[text](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaKbaEscalationChallengeResponse-challenge-questions-text)

string

Text of the question.

```json
{
  "user_id": "example_id",
  "challenge": {
    "id": "Adf2345",
    "type": "kba",
    "questions": [
      {
        "id": "Z9D0iK",
        "text": "What city were you born in?"
      },
      {
        "id": "ch7SbY",
        "text": "Where did you go to high school?"
      },
      {
        "id": "36b4Xo",
        "text": "What is your mother's maiden name?"
      }
    ]
  }
}
```

\=\*=\*=\*=

#### 202 response for TOTP 

If Plaid receives the `MfaTotpEscalationChallenge` response from `POST /users/auth_token`, this indicates that the partner doesn't have to send a temporary password because the user already has the temporary password generator on hand, for example in the form of an authenticator app that displays a new passcode every 60 seconds. If Plaid receives this response, Plaid:

1.  Prompts the user in Plaid Link to fill in the TOTP and waits for them to fill it in.
2.  Sends the TOTP the user entered for validation using the `POST /users/{user_id}/2fa` request. For more information see [Validate 2FA](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#validate-2fa) .

##### MfaTotpEscalationChallenge response 

Prompts for a temporary password from an on-hand password generator.

**Properties**

[user\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-user-id)

required, string

Opaque user identifier.

[challenge](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge)

required, object

The prompt

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-type)

Type of MFA escalation.

[fido2](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-type-fido2)

string

Cryptographic authenticator, via FIDO2.

[otp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-type-otp)

string

One-time passcode. The partner delivers this out of band from this API, for example through email or voice.

[kba](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-type-kba)

string

Knowledge-based authentication, question/response-based challenge method.

[push](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-type-push)

string

Coordinated push notification, requiring acknowledgement.

[totp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-type-totp)

string

Time-based one-time passcode. The user accesses this code through on-hand devices, for example, an authenticator app that displays a new passcode every 60 seconds.

[prompt](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#MfaTotpEscalationChallengeResponse-challenge-prompt)

string

The text prompting users for the passcode. Plaid will relay the user's locale using the Accept-Language header. If the partner doesn't provide this text, Plaid falls back to its own prompt wording.

```json
{
  "user_id": "example_id",
  "challenge": {
    "id": "Adf2345",
    "type": "totp",
    "prompt": "Enter your one-time password."
  }
}
```

###### 401 Unauthorized 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

###### 403 Forbidden 

This response indicates the user’s account is locked, typically due to excessive incorrect authentication attempts. This response will trigger messaging to the user indicating that the account has been temporarily locked, and will advise the user to contact the institution.

###### 405 Not Allowed 

This response indicates that the user’s account is not permitted to participate in aggregation, typically because the user must accept a license or terms of use. This will trigger messaging to the user indicating that the account is not yet authorized for online use, and will direct the user to visit the partner institution’s online portal for further guidance.

Plaid recommends that whatever pending terms or agreements that block this use case be presented to the user immediately upon login.

\=\*=\*=\*=

#### Trigger OTP 

#### POST /users/{user\_id}/sendOtp 

In the case of OTP authentication, provides Plaid with a mechanism to trigger partner-initiated delivery of OTP to the user’s selected send method.

**Request fields**

[challenge\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-{user_id}-sendotp-request-challenge-id)

required, string

The ID for the escalation flow instance.

[send\_method\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-{user_id}-sendotp-request-send-method-id)

required, string

The ID for the send method.

```bash
curl -X POST 'https://your-institution.com/users/example_user_id_1/sendOtp' \
    --header'X-PLAID-CLIENT-ID: PLAID' \
    --header 'X-PLAID-SECRET: example_secret' \
    --header 'X-PLAID-VERSION: 2021-03-26' \
    --header 'Accept: application/json'  \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'challenge_id=36b4Xo&send_method_id=Z9D0iK' \
```

##### Responses 

###### 200 OK 

This response indicates that the send method was acceptable and the partner institution will transmit the passcode to the user. No response body is required.

###### 400 Bad Request 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

###### 503 

Signifying the institution is currently unavailable to respond to the request.

**Properties**

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error)

required, object

Generic error object.

[retry\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-retry-at)

string

The time, in UTC, when the institution is expected to support aggregation again.  
  

Format: `date-time`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

\=\*=\*=\*=

#### Validate 2FA 

##### POST /users/{user\_id}/2fa 

`POST /users/{user_id}/2fa` receives and validates the user's response to the escalation challenge. This is the final endpoint Plaid request in all multi-factor flow types.

Plaid sends one of the following request bodies to this endpoint:

*   `ValidateOtpChallengeRequest`
*   `ValidateKbaChallengeRequest`

See the following sections for details.

\=\*=\*=\*=

#### Validate TOTP or OTP 

###### ValidateOtpChallengeRequest 

Request to validate TOTP or OTP code.

**Properties**

[challenge\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#ValidateOtpChallengeRequest-challenge-id)

required, string

The ID for the escalation flow instance.

[passcode](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#ValidateOtpChallengeRequest-passcode)

required, string

The submitted TOTP or OTP passcode.

```json
{
  "passcode": "123456"
}
```

```bash
curl  --location --request POST
'https://your-institution.com/users/user123/2fa/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-PLAID-CLIENT-ID: example_ID' \
--header 'X-PLAID-SECRET: example_secret' \
--header 'X-PLAID-VERSION: 2021-03-26' \
--header 'Accept: application/json' \
--data-urlencode 'passcode=123456&challenge_id=example_id'
```

\=\*=\*=\*=

#### Validate KBA 

###### ValidateKbaChallengeRequest 

Request to validate KBA challenge answers.

**Properties**

[challenge\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#ValidateKbaChallengeRequest-challenge-id)

required, string

The ID for the escalation flow instance.

[answers](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#ValidateKbaChallengeRequest-answers)

required, \[object\]

[question\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#ValidateKbaChallengeRequest-answers-question-id)

string

The ID for the challenge question.

[text](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#ValidateKbaChallengeRequest-answers-text)

string

The submitted answer.

```json
{}
```

```bash
curl  --location --request POST 'https://your-institution.com/users/user123/2fa/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-PLAID-CLIENT-ID: example_ID' \
--header 'X-PLAID-SECRET: example_secret' \
--header 'X-PLAID-VERSION: 2021-03-26' \
--header 'Accept: application/json' \
--data-urlencode 'challenge_id=string' \
--data-urlencode 'answers[0].question_id=string' \
--data-urlencode 'answers[0].text=San Francisco' \
--data-urlencode 'answers[1].question_id=string2' \
--data-urlencode 'answers[1].text=Billings High School'
```

###### Responses 

###### 200 OK 

The challenge response was correct. The partner returns the access token in the `AuthenticationResponse`.

**Response fields** and example

[user\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-{user_id}-2fa-response-user-id)

required, string

Opaque user identifier.

[auth\_token](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#users-{user_id}-2fa-response-auth-token)

required, string

Opaque, revocable token.

```json
{
  "user_id": "YRQ8PPaohJ",
  "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"
}
```

###### 400 Bad Request 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

###### 401 Not Authorized 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

###### 503 

Signifying the institution is currently unavailable to respond to the request.

**Properties**

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error)

required, object

Generic error object.

[retry\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-retry-at)

string

The time, in UTC, when the institution is expected to support aggregation again.  
  

Format: `date-time`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#InstitutionErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

---


# Changelog | Plaid Docs

Plaid Exchange Changelog 
=========================

#### Track changes to Plaid Exchange 

Plaid Exchange continues to evolve alongside the needs of our integration partners. Below you will find details of the changes made over time to the specification, starting from October 2021.

For information regarding changes to the Plaid API, Plaid Link, and major changes to the Plaid Dashboard, SDKs, functionality, and libraries, see the [Plaid changelog](https://plaid.com/docs/changelog/index.html.md) .

### Spring 2023 

*   [Liabilities](https://plaid.com/docs/liabilities/index.html.md) support added
*   [PKCE Support](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#authorization-flow) added
*   [Cursor paging support](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#transactionsresponse) added for transactions

### Summer/Fall 2022 

*   Support for OAuth 2.0 (Non-OIDC) added
*   Batch processing for transactions
*   Deprecated support for Credentials authorization

### October 2021 

*   Closed beta for the Exchange Validation Tool
*   Launch of the Plaid Exchange Documentation site

---


# Implementation Guide | Plaid Docs

Implementation Guide 
=====================

#### Plaid Exchange Implementation guide 

Scoping and implementation setup 
---------------------------------

Review the [Plaid Exchange API Reference documentation](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/index.html.md)

Prepare one or more test accounts for each type of account you support (checking, savings, credit card, loan, 401k, etc.) Ensure that:

*   All accounts have balance data.
*   All accounts have contact data.
*   Depository, loan, and investment accounts have transaction data.
*   Depository accounts have payment networks data.
*   Negative test accounts (accounts in a bad state).

### IP allowlist 

```json
["18.214.218.91", "3.211.30.208", "3.214.25.67", "54.88.74.128", "54.208.59.10", "54.88.202.28", "34.199.37.46", "35.168.137.48", "3.215.49.214", "34.202.178.138", "52.0.205.192", "52.3.166.211", "35.174.147.86", "52.88.82.239", "52.41.247.19", "3.233.249.56", "35.153.85.253", "3.219.116.195"]
```

If in testing, also add the following

```json
["104.131.160.201", "3.80.88.60"]
```

### Building and testing 

##### Develop and test authentication 

*   Issue Plaid a [Client ID and Secret](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md#client-id-and-client-secret) .
*   Build / Test OAuth flow according to [guidelines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md) .

Note: Plaid Exchange can support MFA/OTP authorization patterns, but it is not recommended.

##### Develop and test Plaid Exchange Endpoints 

Use the [Plaid Exchange API Reference](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/index.html.md) to guide endpoint creation.

*   `/oauth2/auth`: OAuth 2.0 Auth flow
*   `/oauth2/token`: OAuth 2.0 Token flow
*   `/users/{user_id}`: Retrieve account and identity information
*   `/users/{user_id}/transactions`: Retrieve transaction history

### Go-live 

##### Get ready for production 

Confirm your organization's name, logo, and URL. Plaid uses this information to populate your organization's details in Plaid Link. Your logo file must be a 96x96 circular PNG and under 2MB If you would like to make an external launch announcement, reach out to our Plaid team to finalize plans

##### Pilot and migrate 

(Note: This section only applies to existing Plaid partners)

If your institution is already supported in Plaid Link or you are a platform provider with numerous institutions, we will partner together to develop a pilot and migration plan. Migrations typically have 4 phases:

|  | Phase | Description | Timeline |
| --- | --- | --- | --- |
| 1 | Friends and Family Testing | Limited access, internal user traffic | ~ 2 weeks |
| 2 | Pilot Cohort | Enable new connections in production for pilot cohort, monitor health and resolve issues | ~ 2 weeks |
| 3 | Remaining Cohorts | Enable new connections in production for pilot cohort, monitor health and resolve issues # of cohorts is partner dependent | ~ 2-3 weeks |
| 4 | Existing User Migration | After integration health is validated, Plaid will begin a process to migrate all existing items over to the OAuth + API connection. | ~120 days |

*   Timeline illustrative. Speed contingent on ability to validate institutional health, address any open issues etc.

### Ongoing management 

We will continue to partner together to ensure integration quality after you go live on API connectivity with Plaid. Key integration health metrics Plaid monitors include: conversion, data access success rate, data availability and accuracy.

Update the Plaid team with the correct point of contact to support ongoing integration health Log the variables below to help troubleshoot any potential issues with the integration:

*   OAuth flow: log `oauth_state_id`
*   API connections: log `FI_UNIQUE_ID`

---


# Home - Welcome | Plaid Docs

Welcome 
========

#### Plaid Exchange Documentation Portal. 

Introduction 
-------------

This API specification is intended for reference purposes only. New data partners should not use this guide to build their integration. Please refer to our latest API specification, Core Exchange, for the most up-to-date and supported integration approach compatible with the FDX standard. For more information, visit the [Core Exchange docs](https://plaid.comhttps://plaid.com/core-exchange/docs/index.html.md) .

The Plaid Exchange API specification facilitates building of the following endpoints:

*   `/oauth2/auth`: OAuth 2.0 Auth flow
*   `/oauth2/token`: OAuth 2.0 Token flow
*   `/users/{user_id}`: Retrieve account and identity information
*   `/users/{user_id}/transactions`: Retrieve transaction history

Data connectivity benefits 
---------------------------

### Plaid network 

Once your Plaid Exchange API has successfully been validated by Plaid, your organization will appear in the list of available apps in Plaid Link. See the [Plaid Link Demo](https://plaid.com/demo/) for a visual walkthrough of an end-user's experience.

### Security flow 

Plaid uses your OAuth 2.0 flow to allow your users to connect their financial accounts to their other financial applications. Industry standards such as mTLS and PKCE are also supported in the current version.

Prospective customer support 
-----------------------------

If you have a question about Plaid Exchange capabilities that isn't answered in the docs, [contact the Plaid Exchange sales team](https://plaid.com/data-connectivity-core-exchange/#contactForm) to learn more.

---


# Aggregation - Plaid Exchange Reference | Plaid Docs

Aggregation API Reference 
==========================

#### Plaid Exchange Data Aggregation Reference 

This API enables Plaid to make recurrent, user-absent requests in order to maintain a current and consistent view of a user’s permissioned accounts.

\=\*=\*=\*=

#### Get Account and Identity Endpoint 

`GET /users/{user_id}`

Provide user and account information for a given user ID. This endpoint contains the information necessary for the partner to support the Identity and Auth products.

###### Responses 

###### 200 OK 

The request is authorized.

###### UserAccountInfoResponse 

Basic account and identity enumeration.

**Properties**

[identities](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#UserAccountInfoResponse-identities)

required, array

List of Identity instances necessary to fully resolve all records in `accounts`.  
  

Min items: `1`

[user\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#UserAccountInfoResponse-user-identity-id)

required, string

Indicate the Identity corresponding to the currently logged-in user.

[securities](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#UserAccountInfoResponse-securities)

required, array

List of Securities necessary to fully resolve all records in `accounts`.  
  

Min items: `0`

[accounts](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#UserAccountInfoResponse-accounts)

required, array

List of all accounts for which this user is an owner or interested non-owner.

```json
{
  "user_identity_id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
  "identities": [
    {
      "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
      "name": "Jane Doe",
      "email": "jane@plaid.com"
    }
  ],
  "accounts": [
    {
      "id": "account_5921",
      "isin": "US17275R1023",
      "name": "CISCO SYSTEMS INC",
      "symbol": "CSCO",
      "is_cash_equivalent": true,
      "current_price": "100.95",
      "current_as_of": "2018-08-28",
      "close_price": "100.95",
      "type": "cash",
      "currency": "USD",
      "non_iso_currency": null
    }
  ],
  "securities": [
    {
      "id": "R13oiR6lC5jNC5jK",
      "last_activity_at": "2018-08-28",
      "ownership_type": "individual",
      "owner_identity_ids": [
        "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
      ],
      "non_owner_identity_ids": null,
      "status": "active",
      "type": "depository",
      "subtype": "cash management",
      "name": "Vacation Money",
      "official_name": "Pro Checking",
      "display_mask": "9833",
      "opening_date": "2018-08-28",
      "current_balance": "100.95",
      "available_balance": "100.95",
      "tax_advantaged": true,
      "currency": "USD",
      "non_iso_currency": null
    }
  ]
}
```

Privacy Implications of Per-User Request Model

Plaid’s privacy guarantee to end users is that it will never share per-account data, including knowledge of the existence of individual accounts, with applications unless the user has affirmatively indicated those accounts and applications should be linked. Plaid also will also minimize the storage details of accounts retrieved through this API which are not linked to any applications.

At times, it is necessary to communicate information about accounts not connected to any Plaid-powered applications, primarily for the purpose of enabling sensible UX, e.g. when drawing account selection screens. To ease implementation, this API operates at a per-user granularity and not a per-account granularity, because Plaid assumes the responsibility of providing a privacy-conscious view of the user’s accounts to each application.

However, Plaid provides the [NotionalAccount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#notionalaccount) and [BasicIdentity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#basicidentity) models to enable implementers, if desired, to mask the existence of identities and accounts it knows are not linked to any Plaid applications. The partner is expected to use the [Authorization API](https://plaid.comhttps://plaid.com/plaid-exchange/docs/authentication/index.html.md) to ensure its access policy is synchronized with that of Plaid’s, i.e. both Plaid and the partner see the same items. Failure to do so will result in an inconsistent state and degraded end-user experiences.

##### 304 Not Changed 

If present, Plaid will consume the [ETag](https://plaid.comhttps://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag/index.html.md) header, and then present the most-recently seen `ETag` using the `If-None-Match` header on subsequent requests. If there has been no activity on, and no change to, the customer’s account, the partner may return `304 Not Changed` with an empty HTTP body. Plaid will end the session and send no more requests until the next scheduled update.

It is recommended to generate `ETags` by concatenating and hashing the `account_ids` and `last_activity_at` timestamps for all accounts present in the response. If any identity data has changed, the `ETag` should always be new.

\=\*=\*=\*=

#### Get Transactions Endpoint 

`GET /users/{user_id}/transactions`

Provides a query interface for a user’s transactions across all accounts, optionally filtered by posting date.

###### Parameters 

#### Retrieve user transactions. 

Provides a query interface for a user’s transactions across all accounts, optionally filtered by posting date.

**Request fields**

[user\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#users-{user_id}-transactions-request-user-id)

string

Opaque user identifier.

In: `path`

[start](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#users-{user_id}-transactions-request-start)

integer

The offset from the beginning of the result set. For example, if `start` is set to 500, the results set will start with the 501st transaction. (If this parameter is not provided, the results set will start with the 1st transaction by default.)  
  

Default: `0`

In: `query`

[limit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#users-{user_id}-transactions-request-limit)

integer

The number of transactions to return in a given results set. For example, if `limit` is set to 10, the response will be limited to 10 transactions. (If this parameter is not provided, the results set to include up to 500 transactions by default.)  
  

Default: `500`

In: `query`

[start\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#users-{user_id}-transactions-request-start-date)

string

Oldest posting date from which to start returning transactions. If not provided, default to 30 days ago.  
  

Format: `date`

In: `query`

[end\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#users-{user_id}-transactions-request-end-date)

string

Most recent posting date for which transactions may be included. If not provided, default to the current date.  
  

Format: `date`

In: `query`

Note

When considering whether a pending transaction (one which has not yet posted) should be included in a `TransactionsResponse`, evaluate whether the transaction date (`transacted_at`) falls within the range.

##### Responses 

###### 200 OK 

The request was authorized and well-formed.

###### TransactionsResponse 

Successful response to Transactions request. Either offset or total can be used when paging. If both are used, total will be used instead of offset.

**Properties**

[total](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#TransactionsResponse-total)

integer

The number of transactions matching the request. This must count the _total number of transactions_ matching the query, not just the length of this response.  
A natural number, i.e. a non-negative integer.  
  

Minimum: `0`

[offset](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#TransactionsResponse-offset)

string

A cursor string that represents the next page of transactions. Sending a blank offset will indicate the final page.  
Initial call will be a 0.

[transactions](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md#TransactionsResponse-transactions)

required, array

Sequence of BaseTransaction subclass instances, across all accounts, matching the query.

```json
{
  "total": 1,
  "transactions": [
    {
      "type": "transfer",
      "pending": false,
      "amount": "250",
      "fee_amount": "0",
      "reward_amount": "0",
      "reward_rate": "0",
      "transfer_account_id": "3AP9Lwoo3s30E",
      "method": "eft",
      "id": "6AOU0jwFQw3sMZJ",
      "account_id": "account1234",
      "description": "Finance Charge",
      "memo": "Transfer to Checking",
      "category": null,
      "tags": null,
      "ending_balance": "1820.95",
      "transacted_at": "2019-08-24T14:15:22Z",
      "settled_at": "2019-08-25T08:15:42Z",
      "spender_identity_id": "uid_1234",
      "merchant_identity_id": null,
      "geolocation": {
        "coordinates": {
          "lat": 40.7128,
          "lon": 74.006
        },
        "city": "New York",
        "region": "US-NY",
        "country": "US"
      },
      "reward_currency": "USD",
      "reward_non_iso_currency": null,
      "currency": "USD",
      "non_iso_currency": null
    }
  ]
}
```

---


# Data Definitions | Plaid Docs

Data Definitions 
=================

#### Plaid Exchange Data Definitions 

Getting started 
----------------

Before building your Plaid Exchange integration, please review the data definitions here. This will help you ensure your data is correctly formatted and that type matching requirements are met. Use this guide in combination with the API Reference for data aggregation and errors.

##### Notes 

*   Non-required parameters may be left blank, sent as `null`, or omitted. We recommend sending a blank field, as this is slightly cleaner.
    
*   Some required parameters are nullable (`description`, `settled_at`). In these cases, the parameter will be marked as nullable in the parameters list.
    

Primitives 
-----------

Basic types used in other definitions

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-id)

string

A globally unique identifier (`accountId`, `transactionId`, `identityId`, etc.) which can serve as a stable identifier for the associated entity.

[amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-amount)

string

Fixed point decimal number, carried up to six decimal places.

[natural](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-natural)

integer

A natural number i.e. a non-negative integer.

[rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-rate)

string

Fixed-point representation of a normalized rate, carried up to four decimal places.

[iso4217](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-iso4217)

string

ISO-4217 currency code.

[iso8601](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-iso8601)

string

ISO-8601 formatted date or timestamp.  
  

Format: `date`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Primitives-mcc)

string

Merchant category code.

\=\*=\*=\*=

#### Identifiers 

Many compound definitions in this API will make use of ad hoc identifier types, e.g. `accountId`, `identityId`, `transactionId`. These are string values, expected to remain stable during the life of the associated entity, and enable us to reconcile entities across state transitions, e.g. transactions moving from pending to posted state, or a customer’s personal name change.

\=\*=\*=\*=

#### GeoLocation 

Geographic location.

**Properties**

[coordinates](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoLocation-coordinates)

object

Geographic coordinates in [EPSG:4326 WGS84](https://epsg.io/4326) (lat/long)

[lat](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoLocation-coordinates-lat)

number

Latitude coordinate.

[lon](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoLocation-coordinates-lon)

number

Longitude coordinate.

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoLocation-city)

string

City name.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoLocation-region)

string

Region identifier.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoLocation-country)

string

Country identifier.

```json
{
  "coordinates": {
    "lat": 41.8574,
    "lon": -71.39862
  },
  "city": "New York",
  "region": "US-NY",
  "country": "US"
}
```

\=\*=\*=\*=

#### GeoCoordinates 

Geographic coordinates in [EPSG:4326 WGS84](https://epsg.io/4326) (lat/long)

**Properties**

[lat](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoCoordinates-lat)

required, number

Latitude coordinate.

[lon](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#GeoCoordinates-lon)

required, number

Longitude coordinate.

```json
{
  "lat": 41.8574,
  "lon": -71.39862
}
```

Account 
--------

\=\*=\*=\*=

#### Currencies 

All account subtypes include `currency` and `non_iso_currency` properties to indicate the currencies in which their balances are denominated. One and only one of these two fields should be set, with the other being unset (not present). If the account is denominated in a currency recognized under [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) , then currency should be set to that currency’s alphabetic code under that standard.

However, if the balance is denominated in a non-ISO currency, e.g. Bitcoin, mileage, or reward points, then currency must be null and `non_iso_currency` should be used instead. In this case, Plaid does not guarantee that balances across accounts, and across institutions, refer to the same currency even when they use the same `non_iso_currency` values.

\=\*=\*=\*=

#### Account Ownership 

When modeling account ownership, include only the identities that are interesting when understanding a user’s financial situation and capability. For example, joint account ownership between a husband and wife should be modeled as two owner\_identity\_ids. Business account ownership should be modeled as a single business owner (use `BusinessIdentity`), which then has `owner_identity_ids` related to it, representing the beneficial owners (those with at least a 25% stake). Identification of business-owned depository accounts is critical for funds transfer use cases (e.g. payments), e.g. in the US, ACH transfers are required to distinguish B2B transactions from individual or B2C transactions.

Interested non-ownership identities should be included when doing so would further illustrate the user’s situation. For example, when the user is a trustee of an account, their identity should be included in `non_owner_identity_ids`. Inclusion of personally identifying information should always be balanced against visibility and consent concerns. Identity information not necessary for the currently authorized user to transact against the account should be limited, and those identities should be modeled using BasicIdentity e.g. when the trustor on an account is transacting, identifying information about the trustee need not be extensive. Conversely, if the trustee were viewing the account, their entry in `non_owner_identity_ids` can be more complete, and the trustor’s entry can be more limited.

Plaid’s account ownership model is intended to support compliance with ownership guidelines set forth in the FDIC Publication, ["Your Insured Deposits"](https://www.fdic.gov/resources/deposit-insurance/brochures/insured-deposits/) and in the US Treasury FinCEN publication, ["FIN-2018-G001"](https://www.fincen.gov/sites/default/files/2018-04/FinCEN_Guidance_CDD_FAQ_FINAL_508_2.pdf) (Anti-Money Laundering Guidance document).

Ownership structure of an account.

**Properties**

[individual](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountOwnership-individual)

Individual account.

[joint](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountOwnership-joint)

Joint account ownership.

[association](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountOwnership-association)

Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations.

[trust](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountOwnership-trust)

Revocable or irrevocable trust.

\=\*=\*=\*=

#### Account Status 

Report accounts until they are closed, and continue reporting closed accounts until 90 days after closure.

**Properties**

[active](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-active)

Account has current activity and there are no issues outstanding.

[inactive](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-inactive)

Account has seen no activity for a standard period defined by the institution, and may be subject to fees or at risk of closure.

[frozen](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-frozen)

Access to and transaction against the account is prohibited due to legal or compliance concerns, e.g. assets subject to OFAC sanctions enforcement, assets subject to a discovery subpoena, etc.

[locked](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-locked)

Access to the account is prohibited due to security concerns, e.g. fraudulent activity observed.

[flagged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-flagged)

All activity is prohibited due to regulatory or policy requirements, e.g. monthly withdrawals from a savings account in excess of FRB Regulation D.

[restricted](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-restricted)

Activity on the account is restricted, e.g. withdrawals are subject to a daily limit, until the user meets certain conditions.

[closed](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountStatus-closed)

The account is closed.

##### Suspended Access 

There are multiple statuses listed here which, at first glance, seem to describe nearly identical conditions. Although frozen, flagged, and locked all describe conditions where the account’s assets cannot be accessed until they are released, the reasons for suspension differ,

*   `frozen` describes a condition in connection to legal action: use frozen to indicate than an account’s assets may be subject to seizure
*   `flagged` describes a condition where account activity is suspicious, or non-compliant with the customer agreement: use flagged to indicate that the account may be at risk of closure
*   `locked` describes a condition applied proactively to protect the account holder: use locked to indicate that assets are restricted to protect against loss

\=\*=\*=\*=

#### Account Type and Subtype 

| Type | Subtype | Transaction Type | Description |
| --- | --- | --- | --- |
| depository | cash management | DepositoryTransaction | Cash management account |
| depository | cd | DepositoryTransaction | Cash deposit (CD) |
| depository | checking | DepositoryTransaction | Checking account |
| depository | savings | DepositoryTransaction | Savings account |
| depository | money market | DepositoryTransaction | Money market account |
| depository | health | DepositoryTransaction | Any health savings or reimbursement account, e.g. HSA, FSA, HRA etc. |
| depository | prepaid | DepositoryTransaction | Prepaid account, typically debit card |
| depository | gic | DepositoryTransaction | Guaranteed investment certificate (Canada) |
| loan | auto | LoanTransaction | Auto loan |
| loan | commercial | LoanTransaction | Commercial loan |
| loan | construction | LoanTransaction | Construction loan, e.g. 203(k) |
| loan | consumer | LoanTransaction | Consumer installment loan |
| loan | credit card | CreditTransaction | Credit card |
| loan | home equity | LoanTransaction | Loan or line of credit against home collateral, e.g. a HELOC |
| loan | mortgage | LoanTransaction | Home mortgage |
| loan | overdraft | LoanTransaction | Overdraft protection line of credit |
| loan | line of credit | CreditTransaction | Line of credit |
| loan | student | LoanTransaction | Student loan |
| investment | 401a | InvestmentTransaction | IRC 401(a) governmental and nonprofit employee retirement plan |
| investment | 401k | InvestmentTransaction | IRC 401(k) retirement plan |
| investment | 403b | InvestmentTransaction | IRC 403(b) annuity retirement plan |
| investment | 457b | InvestmentTransaction | IRC 457(b) retirement savings account |
| investment | 529 | InvestmentTransaction | IRC 529 educational savings plan |
| investment | brokerage | InvestmentTransaction | Ordinary investment account |
| investment | esa | InvestmentTransaction | Non-529 education savings account (e.g. Coverdell) |
| investment | ira | InvestmentTransaction | Traditional IRA |
| investment | isa | InvestmentTransaction | Individual savings account (UK) |
| investment | lira | InvestmentTransaction | Locked-in retirement account (Canada) |
| investment | other | InvestmentTransaction | Other investment vehicle not covered here |
| investment | rif | InvestmentTransaction | Retirement income fund, includes LIF, LRIF, RRIF, PRIF and other income funds (Canada) |
| investment | rsp | InvestmentTransaction | Retirement savings plan, includes RRSP, RDSP, RESP, LRSP and other savings plans (Canada) |
| investment | pension | InvestmentTransaction | Traditional defined-benefit plan |
| investment | profit-sharing | InvestmentTransaction | Employee profit sharing plan |
| investment | roth ira | InvestmentTransaction | Roth IRA |
| investment | roth 401k | InvestmentTransaction | Roth 401(k) |
| investment | sep ira | InvestmentTransaction | Simplified employee plan IRA |
| investment | simple ira | InvestmentTransaction | SIMPLE IRA |
| investment | sipp | InvestmentTransaction | Self-invested personal pension |
| investment | stock plan | InvestmentTransaction | Stock purchase plan, e.g. ESPP |
| investment | tsp | InvestmentTransaction | Thrift savings plan |
| investment | tfsa | InvestmentTransaction | Tax-free savings account (Canada) |
| investment | custodial | InvestmentTransaction | Account covered under UGMA/UTMA |
| investment | variable annuity | InvestmentTransaction | Variable annuity tax-deferred retirement vehicle |

\=\*=\*=\*=

#### BaseAccount 

List of all accounts for which this user is an owner or interested non-owner.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": null,
  "non_owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "status": "active",
  "type": "depository",
  "subtype": "checking",
  "name": "Vacation Money",
  "official_name": "Pro Checking",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "current_balance": "850.55",
  "available_balance": "149.45",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### DepositoryAccount 

Represents depository accounts, e.g. checking, savings, CDs.

**Properties**

[interest\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-interest-rate)

string

The rate at which this account earns interest.  
  

Pattern: `^\d*(\.\d{1,4})?$`

[transfer\_codes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes)

required, object

Account identifiers necessary for funds transfers.

[ach](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-ach)

object

ACH (US) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-ach-account-number)

string

The account number.

[routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-ach-routing-number)

string

The ABA routing transit number.

[wire\_routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-ach-wire-routing-number)

string

The institution's routing number for wire transfer.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-ach-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-ach-supports-credit)

boolean

Indicates account may be credited using transfer code.

[eft](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-eft)

object

EFT (Canada) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-eft-account-number)

string

The account number.

[institution\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-eft-institution-number)

string

The institution's number assigned by Payments Canada.

[branch\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-eft-branch-number)

string

The branch number corresponding to the account.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-eft-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-eft-supports-credit)

boolean

Indicates account may be credited using transfer code.

[iban](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban)

object

[IBAN](http://www.wikiwand.com/en/International_Bank_Account_Number) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-account-number)

string

The full IBAN.

[bank\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-bank-code)

string

Bank identifier.

[country\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-country-code)

string

The country code.

[location\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-location-code)

string

Location code for the bank's office.

[branch\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-branch-code)

string

Optionally indicate a specific branch.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-iban-supports-credit)

boolean

Indicates account may be credited using transfer code.

[payment\_card](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card)

object

Payment card account identifiers.

[card\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card-card-number)

string

The payment card number.

[expiry\_month](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card-expiry-month)

string

Month of card expiration, as a 2-digit value.

[expiry\_year](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card-expiry-year)

string

Year of card expiration.

[security\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card-security-code)

string

CVV, CSC, or other card-not-present verification value.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-payment-card-supports-credit)

boolean

Indicates account may be credited using transfer code.

[acats](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats)

object

[ACATS](http://www.wikiwand.com/en/Automated_Customer_Account_Transfer_Service) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-account-number)

string

The account number.

[receiving\_member\_identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity)

object

Identity of the receiving brokerage (including `organization`).

[organization](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization)

object

Describes an organization, e.g., a business or non-profit.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-name)

string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[person](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person)

object

Describes an individual, named person.

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-first-name)

string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-middle-name)

string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-last-name)

string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-email)

string

The email address where this entity can be contacted.

[mailing\_address](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address)

object

Description of a street address.

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address-lines)

\[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address-city)

string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address-country)

string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-mailing-address-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-id)

string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-receiving-member-identity-name)

string

The display name of this entity (insufficient for KYC purposes)

[dtcc\_clearing\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-dtcc-clearing-ids)

\[string\]

The [DTCC](http://www.wikiwand.com/en/Depository_Trust_%26_Clearing_Corporation) institution identifiers for the institution holding the account.  
  

Min items: `1`

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-transfer-codes-acats-supports-credit)

boolean

Indicates account may be credited using transfer code.

[maturity\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-maturity-date)

string

The date of maturity for fixed-term instruments, e.g. CDs.  
  

Format: `date`

[statements](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-statements)

\[object\]

Must describe statement periods for previous two years.

[statement\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-statements-statement-id)

string

Globally unique identifier for this statement.

[open\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-statements-open-date)

string

The opening date of this statement period.  
  

Format: `date`

[close\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-statements-close-date)

string

The closing date of this statement period, use a future date if the statement period has not closed.  
  

Format: `date`

[balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-statements-balance)

string

The balance at the close of the statement period.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[document\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-statements-document-url)

string

A URL to a downloadable document form of this statement. Implementers should not assume that accessors of this URL are always authorized.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "interest_rate": "0.0199",
  "transfer_codes": {
    "ach": {
      "account_number": "string",
      "routing_number": "031176110",
      "wire_routing_number": "string",
      "supports_debit": true,
      "supports_credit": true
    },
    "eft": {
      "account_number": "string",
      "institution_number": "004",
      "branch_number": "1320",
      "supports_debit": true,
      "supports_credit": true
    },
    "iban": {
      "account_number": "string",
      "bank_code": "NORD",
      "country_code": "FR",
      "location_code": "ZZ",
      "branch_code": "80A",
      "supports_debit": true,
      "supports_credit": true
    },
    "payment_card": {
      "card_number": "string",
      "expiry_month": "01",
      "expiry_year": "2021",
      "security_code": "363",
      "supports_debit": true,
      "supports_credit": true
    },
    "acats": {
      "account_number": "string",
      "receiving_member_identity": {
        "organization": {
          "name": "Doe Business, Inc.",
          "structure": "sole",
          "mcc": "5542",
          "owner_identity_ids": [
            "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
          ],
          "tax_identifier": {
            "tax_authority": "IRS",
            "tax_payer_id": "string"
          }
        },
        "person": {
          "first_name": "Jane",
          "middle_name": "Joan",
          "last_name": "Doe",
          "date_of_birth": "1987-01-31",
          "tax_identifier": {
            "tax_authority": "IRS",
            "tax_payer_id": "string"
          }
        },
        "email": "jane@plaid.com",
        "mailing_address": {
          "lines": [
            "413 Leeward Way",
            "Apt 3A"
          ],
          "city": "San Francisco",
          "region": "US-CA",
          "country": "US",
          "postal_code": "94106",
          "phone": "+1 415 555 1212"
        },
        "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
        "name": "Jane Doe"
      },
      "dtcc_clearing_ids": [
        "string"
      ],
      "supports_debit": true,
      "supports_credit": true
    }
  },
  "maturity_date": "2018-08-28",
  "statements": [
    {
      "statement_id": "string",
      "open_date": "2018-08-28",
      "close_date": "2018-08-28",
      "balance": "100.95",
      "document_url": "string"
    }
  ],
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "non_owner_identity_ids": null,
  "status": "active",
  "type": "depository",
  "subtype": "checking",
  "name": "Vacation Money",
  "official_name": "Pro Checking",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "current_balance": "850.55",
  "available_balance": "149.45",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### DepositoryAccountStatement 

Represents primary account statement details.

**Properties**

[statement\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountStatement-statement-id)

required, string

Globally unique identifier for this statement.

[open\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountStatement-open-date)

string

The opening date of this statement period.  
  

Format: `date`

[close\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountStatement-close-date)

string

The closing date of this statement period, use a future date if the statement period has not closed.  
  

Format: `date`

[balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountStatement-balance)

string

The balance at the close of the statement period.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[document\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountStatement-document-url)

string

A URL to a downloadable document form of this statement. Implementers should not assume that accessors of this URL are always authorized.

```json
{
  "statement_id": "string",
  "open_date": "2018-08-28",
  "close_date": "2018-08-28",
  "balance": "100.95",
  "document_url": "string"
}
```

\=\*=\*=\*=

#### TransferCodeMap 

Mapping between an account and various payment networks.

**Properties**

[ach](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-ach)

object

ACH (US) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-ach-account-number)

string

The account number.

[routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-ach-routing-number)

string

The ABA routing transit number.

[wire\_routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-ach-wire-routing-number)

string

The institution's routing number for wire transfer.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-ach-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-ach-supports-credit)

boolean

Indicates account may be credited using transfer code.

[eft](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-eft)

object

EFT (Canada) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-eft-account-number)

string

The account number.

[institution\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-eft-institution-number)

string

The institution's number assigned by Payments Canada.

[branch\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-eft-branch-number)

string

The branch number corresponding to the account.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-eft-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-eft-supports-credit)

boolean

Indicates account may be credited using transfer code.

[iban](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban)

object

[IBAN](http://www.wikiwand.com/en/International_Bank_Account_Number) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-account-number)

string

The full IBAN.

[bank\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-bank-code)

string

Bank identifier.

[country\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-country-code)

string

The country code.

[location\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-location-code)

string

Location code for the bank's office.

[branch\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-branch-code)

string

Optionally indicate a specific branch.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-iban-supports-credit)

boolean

Indicates account may be credited using transfer code.

[payment\_card](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card)

object

Payment card account identifiers.

[card\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card-card-number)

string

The payment card number.

[expiry\_month](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card-expiry-month)

string

Month of card expiration, as a 2-digit value.

[expiry\_year](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card-expiry-year)

string

Year of card expiration.

[security\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card-security-code)

string

CVV, CSC, or other card-not-present verification value.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-payment-card-supports-credit)

boolean

Indicates account may be credited using transfer code.

[acats](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats)

object

[ACATS](http://www.wikiwand.com/en/Automated_Customer_Account_Transfer_Service) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-account-number)

string

The account number.

[receiving\_member\_identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity)

object

Identity of the receiving brokerage (including `organization`).

[organization](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization)

object

Describes an organization, e.g., a business or non-profit.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-name)

string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-organization-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[person](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person)

object

Describes an individual, named person.

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-first-name)

string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-middle-name)

string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-last-name)

string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-person-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-email)

string

The email address where this entity can be contacted.

[mailing\_address](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address)

object

Description of a street address.

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address-lines)

\[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address-city)

string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address-country)

string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-mailing-address-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-id)

string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-receiving-member-identity-name)

string

The display name of this entity (insufficient for KYC purposes)

[dtcc\_clearing\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-dtcc-clearing-ids)

\[string\]

The [DTCC](http://www.wikiwand.com/en/Depository_Trust_%26_Clearing_Corporation) institution identifiers for the institution holding the account.  
  

Min items: `1`

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TransferCodeMap-acats-supports-credit)

boolean

Indicates account may be credited using transfer code.

```json
{
  "ach": {
    "account_number": "string",
    "routing_number": "031176110",
    "wire_routing_number": "string",
    "supports_debit": true,
    "supports_credit": true
  },
  "eft": {
    "account_number": "string",
    "institution_number": "004",
    "branch_number": "1320",
    "supports_debit": true,
    "supports_credit": true
  },
  "iban": {
    "account_number": "string",
    "bank_code": "NORD",
    "country_code": "FR",
    "location_code": "ZZ",
    "branch_code": "80A",
    "supports_debit": true,
    "supports_credit": true
  },
  "payment_card": {
    "card_number": "string",
    "expiry_month": "01",
    "expiry_year": "2021",
    "security_code": "363",
    "supports_debit": true,
    "supports_credit": true
  },
  "acats": {
    "account_number": "string",
    "receiving_member_identity": {
      "organization": {
        "name": "Doe Business, Inc.",
        "structure": "sole",
        "mcc": "5542",
        "owner_identity_ids": [
          "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
        ],
        "tax_identifier": {
          "tax_authority": "IRS",
          "tax_payer_id": "string"
        }
      },
      "person": {
        "first_name": "Jane",
        "middle_name": "Joan",
        "last_name": "Doe",
        "date_of_birth": "1987-01-31",
        "tax_identifier": {
          "tax_authority": "IRS",
          "tax_payer_id": "string"
        }
      },
      "email": "jane@plaid.com",
      "mailing_address": {
        "lines": [
          "413 Leeward Way",
          "Apt 3A"
        ],
        "city": "San Francisco",
        "region": "US-CA",
        "country": "US",
        "postal_code": "94106",
        "phone": "+1 415 555 1212"
      },
      "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
      "name": "Jane Doe"
    },
    "dtcc_clearing_ids": [
      "string"
    ],
    "supports_debit": true,
    "supports_credit": true
  }
}
```

\=\*=\*=\*=

#### DepositoryAccountTransferCode 

Base model for depository account transfer identifiers.

**Properties**

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountTransferCode-supports-debit)

required, boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryAccountTransferCode-supports-credit)

required, boolean

Indicates account may be credited using transfer code.

```json
{
  "supports_debit": true,
  "supports_credit": true
}
```

\=\*=\*=\*=

#### AchTransferCode 

Account and routing number for directing funds transfers in the US.

**Properties**

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AchTransferCode-account-number)

required, string

The account number.

[routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AchTransferCode-routing-number)

required, string

The ABA routing transit number.

[wire\_routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AchTransferCode-wire-routing-number)

string

The institution's routing number for wire transfer.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AchTransferCode-supports-debit)

required, boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AchTransferCode-supports-credit)

required, boolean

Indicates account may be credited using transfer code.

```json
{
  "account_number": "121212454545",
  "routing_number": "031176110",
  "wire_routing_number": "1234-5678-0",
  "supports_debit": true,
  "supports_credit": true
}
```

\=\*=\*=\*=

#### EftTransferCode 

Identifiers for directing funds transfers in Canada.

**Properties**

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#EftTransferCode-account-number)

required, string

The account number.

[institution\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#EftTransferCode-institution-number)

required, string

The institution's number assigned by Payments Canada.

[branch\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#EftTransferCode-branch-number)

required, string

The branch number corresponding to the account.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#EftTransferCode-supports-debit)

required, boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#EftTransferCode-supports-credit)

required, boolean

Indicates account may be credited using transfer code.

```json
{
  "account_number": "string",
  "institution_number": "004",
  "branch_number": "1320",
  "supports_debit": true,
  "supports_credit": true
}
```

\=\*=\*=\*=

#### IbanTransferCode 

[International Bank Account Number](https://www.wikiwand.com/en/International_Bank_Account_Number) for directing international funds transfers.

**Properties**

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-account-number)

required, string

The full IBAN.

[bank\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-bank-code)

required, string

Bank identifier.

[country\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-country-code)

required, string

The country code.

[location\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-location-code)

required, string

Location code for the bank's office.

[branch\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-branch-code)

string

Optionally indicate a specific branch.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-supports-debit)

required, boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#IbanTransferCode-supports-credit)

required, boolean

Indicates account may be credited using transfer code.

```json
{
  "account_number": "string",
  "bank_code": "NORD",
  "country_code": "FR",
  "location_code": "ZZ",
  "branch_code": "80A",
  "supports_debit": true,
  "supports_credit": true
}
```

\=\*=\*=\*=

#### PaymentCardTransferCode 

Identifiers for directing funds to/from payment cards.

**Properties**

[card\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PaymentCardTransferCode-card-number)

required, string

The payment card number.

[expiry\_month](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PaymentCardTransferCode-expiry-month)

required, string

Month of card expiration, as a 2-digit value.

[expiry\_year](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PaymentCardTransferCode-expiry-year)

required, string

Year of card expiration.

[security\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PaymentCardTransferCode-security-code)

required, string

CVV, CSC, or other card-not-present verification value.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PaymentCardTransferCode-supports-debit)

required, boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PaymentCardTransferCode-supports-credit)

required, boolean

Indicates account may be credited using transfer code.

```json
{
  "card_number": "string",
  "expiry_month": "01",
  "expiry_year": "2021",
  "security_code": "363",
  "supports_debit": true,
  "supports_credit": true
}
```

\=\*=\*=\*=

#### NotionalAccount 

A placeholder entity, capable of indicating only basic facts about an account.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-id)

required, string

Permanent account identifier. Should be an `accountId`. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-type)

required, string

Major classification of this account. Should be one of the `accountType` values.

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-subtype)

required, string

Minor classification of this account. Should be one of the `accountSubtype` values.

[access\_authorized](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-access-authorized)

deprecated, boolean

Indicate that the user has not authorized the account to participate in aggregation. should only be present/true for notional accounts.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-name)

string

The account’s user-given name, if the institution supports naming of accounts

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-official-name)

required, string

The account’s marketing or brand name.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NotionalAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency’s symbol.

```json
{
  "id": "R13oiR6lC5jNC5jK",
  "type": "depository",
  "subtype": "checking",
  "name": "Vacation money",
  "official_name": "Pro Checking",
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### InvestmentAccount 

Representation of brokerage accounts.

**Properties**

[transfer\_codes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes)

object

Account identifiers necessary for portfolio transfers.

[ach](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-ach)

object

ACH (US) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-ach-account-number)

string

The account number.

[routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-ach-routing-number)

string

The ABA routing transit number.

[wire\_routing\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-ach-wire-routing-number)

string

The institution's routing number for wire transfer.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-ach-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-ach-supports-credit)

boolean

Indicates account may be credited using transfer code.

[eft](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-eft)

object

EFT (Canada) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-eft-account-number)

string

The account number.

[institution\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-eft-institution-number)

string

The institution's number assigned by Payments Canada.

[branch\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-eft-branch-number)

string

The branch number corresponding to the account.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-eft-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-eft-supports-credit)

boolean

Indicates account may be credited using transfer code.

[iban](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban)

object

[IBAN](http://www.wikiwand.com/en/International_Bank_Account_Number) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-account-number)

string

The full IBAN.

[bank\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-bank-code)

string

Bank identifier.

[country\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-country-code)

string

The country code.

[location\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-location-code)

string

Location code for the bank's office.

[branch\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-branch-code)

string

Optionally indicate a specific branch.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-iban-supports-credit)

boolean

Indicates account may be credited using transfer code.

[payment\_card](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card)

object

Payment card account identifiers.

[card\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card-card-number)

string

The payment card number.

[expiry\_month](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card-expiry-month)

string

Month of card expiration, as a 2-digit value.

[expiry\_year](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card-expiry-year)

string

Year of card expiration.

[security\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card-security-code)

string

CVV, CSC, or other card-not-present verification value.

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-payment-card-supports-credit)

boolean

Indicates account may be credited using transfer code.

[acats](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats)

object

[ACATS](http://www.wikiwand.com/en/Automated_Customer_Account_Transfer_Service) account identifiers.

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-account-number)

string

The account number.

[receiving\_member\_identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity)

object

Identity of the receiving brokerage (including `organization`).

[organization](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization)

object

Describes an organization, e.g., a business or non-profit.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-name)

string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-organization-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[person](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person)

object

Describes an individual, named person.

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-first-name)

string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-middle-name)

string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-last-name)

string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-person-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-email)

string

The email address where this entity can be contacted.

[mailing\_address](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address)

object

Description of a street address.

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address-lines)

\[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address-city)

string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address-country)

string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-mailing-address-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-id)

string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-receiving-member-identity-name)

string

The display name of this entity (insufficient for KYC purposes)

[dtcc\_clearing\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-dtcc-clearing-ids)

\[string\]

The [DTCC](http://www.wikiwand.com/en/Depository_Trust_%26_Clearing_Corporation) institution identifiers for the institution holding the account.  
  

Min items: `1`

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-supports-debit)

boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-transfer-codes-acats-supports-credit)

boolean

Indicates account may be credited using transfer code.

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[margin\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-margin-balance)

string

The amount that is on loan. Provide as a negative amount.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[margin\_limit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-margin-limit)

string

The total limit of the margin extended to the account.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[margin\_equity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-margin-equity)

string

The amount of marginable assets owned in the account.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[maintenance\_margin](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-maintenance-margin)

string

The minimum equity needed to hold the positions in the account.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[buying\_power](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-buying-power)

string

Total amount of funds available for making transactions, includes margin.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[current\_as\_of](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-current-as-of)

string

The time at which `current_balance` was current.  
  

Format: `date-time`

[holdings](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings)

required, \[object\]

Descriptions of held assets in the account.

[security\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-security-id)

string

The identifier of the security referenced by this holding.

[cost\_basis](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-cost-basis)

string

The total cost of acquiring this holding, inclusive of fees.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[quantity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-quantity)

string

The amount of the security (typically, number of shares) comprising this holding.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[lots](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-lots)

object

The tax lots constituting this holding.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-lots-id)

string

The unique and permanent identifier for this lot.

[acquired\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-lots-acquired-at)

string

The date at which the lot was acquired.  
  

Format: `date`

[acquired\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-lots-acquired-price)

string

The total price at which this lot was acquired.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[quantity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-lots-quantity)

string

The quantity held in this lot.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-holdings-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "transfer_codes": {
    "ach": {
      "account_number": "string",
      "routing_number": "031176110",
      "wire_routing_number": "string",
      "supports_debit": true,
      "supports_credit": true
    },
    "eft": {
      "account_number": "string",
      "institution_number": "004",
      "branch_number": "1320",
      "supports_debit": true,
      "supports_credit": true
    },
    "iban": {
      "account_number": "string",
      "bank_code": "NORD",
      "country_code": "FR",
      "location_code": "ZZ",
      "branch_code": "80A",
      "supports_debit": true,
      "supports_credit": true
    },
    "payment_card": {
      "card_number": "string",
      "expiry_month": "01",
      "expiry_year": "2021",
      "security_code": "363",
      "supports_debit": true,
      "supports_credit": true
    },
    "acats": {
      "account_number": "string",
      "receiving_member_identity": {
        "organization": {
          "name": "Doe Business, Inc.",
          "structure": "sole",
          "mcc": "5542",
          "owner_identity_ids": [
            "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
          ],
          "tax_identifier": {
            "tax_authority": "IRS",
            "tax_payer_id": "string"
          }
        },
        "person": {
          "first_name": "Jane",
          "middle_name": "Joan",
          "last_name": "Doe",
          "date_of_birth": "1987-01-31",
          "tax_identifier": {
            "tax_authority": "IRS",
            "tax_payer_id": "string"
          }
        },
        "email": "jane@plaid.com",
        "mailing_address": {
          "lines": [
            "413 Leeward Way",
            "Apt 3A"
          ],
          "city": "San Francisco",
          "region": "US-CA",
          "country": "US",
          "postal_code": "94106",
          "phone": "+1 415 555 1212"
        },
        "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
        "name": "Jane Doe"
      },
      "dtcc_clearing_ids": [
        "string"
      ],
      "supports_debit": true,
      "supports_credit": true
    }
  },
  "current_balance": "850.55",
  "available_balance": "149.45",
  "margin_balance": "100.95",
  "margin_limit": "100.95",
  "margin_equity": "100.95",
  "maintenance_margin": "100.95",
  "buying_power": "100.95",
  "current_as_of": "2018-08-28",
  "holdings": [
    {
      "security_id": "string",
      "cost_basis": "100.95",
      "quantity": "100.95",
      "lots": {
        "id": "string",
        "acquired_at": "2018-08-28",
        "acquired_price": "100.95",
        "quantity": "100.95"
      },
      "currency": "USD",
      "non_iso_currency": null
    }
  ],
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "non_owner_identity_ids": null,
  "status": "active",
  "type": "investment",
  "subtype": "401k",
  "name": "Vacation Money",
  "official_name": "401k Account",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### AcatsTransferCode 

[Automated Customer Account Transfer Service](http://www.wikiwand.com/en/Automated_Customer_Account_Transfer_Service) identifiers for transferring stock portfolios between brokerages.

**Properties**

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-account-number)

required, string

The account number.

[receiving\_member\_identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity)

required, object

Identity of the receiving brokerage (including `organization`).

[organization](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization)

object

Describes an organization, e.g., a business or non-profit.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-name)

string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-organization-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[person](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person)

object

Describes an individual, named person.

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-first-name)

string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-middle-name)

string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-last-name)

string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-person-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-email)

string

The email address where this entity can be contacted.

[mailing\_address](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address)

object

Description of a street address.

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address-lines)

\[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address-city)

string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address-country)

string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-mailing-address-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-id)

string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-receiving-member-identity-name)

string

The display name of this entity (insufficient for KYC purposes)

[dtcc\_clearing\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-dtcc-clearing-ids)

required, \[string\]

The [DTCC](http://www.wikiwand.com/en/Depository_Trust_%26_Clearing_Corporation) institution identifiers for the institution holding the account.  
  

Min items: `1`

[supports\_debit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-supports-debit)

required, boolean

Indicates account may be debited using transfer code.

[supports\_credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AcatsTransferCode-supports-credit)

required, boolean

Indicates account may be credited using transfer code.

```json
{
  "account_number": "string",
  "receiving_member_identity": {
    "organization": {
      "name": "Doe Business, Inc.",
      "structure": "sole",
      "mcc": "5542",
      "owner_identity_ids": [
        "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
      ],
      "tax_identifier": {
        "tax_authority": "IRS",
        "tax_payer_id": "string"
      }
    },
    "person": {
      "first_name": "Jane",
      "middle_name": "Joan",
      "last_name": "Doe",
      "date_of_birth": "1987-01-31",
      "tax_identifier": {
        "tax_authority": "IRS",
        "tax_payer_id": "string"
      }
    },
    "email": "jane@plaid.com",
    "mailing_address": {
      "lines": [
        "413 Leeward Way",
        "Apt 3A"
      ],
      "city": "San Francisco",
      "region": "US-CA",
      "country": "US",
      "postal_code": "94106",
      "phone": "+1 415 555 1212"
    },
    "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
    "name": "Jane Doe"
  },
  "dtcc_clearing_ids": [
    "string"
  ],
  "supports_debit": true,
  "supports_credit": true
}
```

\=\*=\*=\*=

#### Security 

Description of a security (i.e. stocks, bonds, derivatives, etc.)

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-id)

required, string

The permanent identifier for this security, across all accounts and holdings. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[isin](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-isin)

string

The ISO 6166-compliant [ISIN](https://www.wikiwand.com/en/International_Securities_Identification_Number) for this security, if available.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-name)

required, string

A descriptive name for the security, suitable for display.

[symbol](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-symbol)

required, string

The security's trading symbol, if applicable. Otherwise, a short, commonly used identifier.

[is\_cash\_equivalent](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-is-cash-equivalent)

required, boolean

Indicates the security is highly-liquid, e.g. a money market account, and should be regarded as cash.

[current\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-current-price)

required, string

The instantaneous trading price of the security.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[current\_as\_of](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-current-as-of)

required, string

The time at which `current_price` was current, in ISO 8601 format.  
  

Format: `date-time`

[close\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-close-price)

string

The price of the security at the most recent close of trading. For securities that are traded continuously throughout the day, use the price at 11:59PM of the previous day, in the institution's time zone.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-type)

required, string

The security type. For detailed descriptions of available types, see [Plaid API security types](https://plaid.com/docs/api/accounts/index.html.md#StandaloneAccountType-investment) .  
  

Possible values: `cash`, `derivative`, `equity`, `etf`, `fixed income`, `loan`, `mutual fund`, `other`

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-currency)

string

The ISO 4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Security-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "id": "account_5921",
  "isin": "US17275R1023",
  "name": "CISCO SYSTEMS INC",
  "symbol": "CSCO",
  "is_cash_equivalent": true,
  "current_price": "100.95",
  "current_as_of": "2018-08-28",
  "close_price": "100.95",
  "type": "cash",
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### OptionSecurity 

Representation of a Security with type of derivative.

**Properties**

[expiry](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-expiry)

required, string

The contract expiration date.  
  

Format: `date`

[contract\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-contract-type)

required, string

The type of option.  
  

Possible values: `put`, `call`

[option\_style](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-option-style)

string

The style of option (US or European)  
  

Possible values: `euro`, `us`

[exercise\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-exercise-price)

string

The price at which the contract owner may transact.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[underlying\_security\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-underlying-security-id)

required, string

Reference to the security underlying this contract.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-id)

required, string

The permanent identifier for this security, across all accounts and holdings. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[isin](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-isin)

string

The ISO 6166-compliant [ISIN](https://www.wikiwand.com/en/International_Securities_Identification_Number) for this security, if available.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-name)

required, string

A descriptive name for the security, suitable for display.

[symbol](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-symbol)

required, string

The security's trading symbol, if applicable. Otherwise, a short, commonly used identifier.

[is\_cash\_equivalent](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-is-cash-equivalent)

required, boolean

Indicates the security is highly-liquid, e.g. a money market account, and should be regarded as cash.

[current\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-current-price)

required, string

The instantaneous trading price of the security.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[current\_as\_of](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-current-as-of)

required, string

The time at which `current_price` was current, in ISO 8601 format.  
  

Format: `date-time`

[close\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-close-price)

string

The price of the security at the most recent close of trading. For securities that are traded continuously throughout the day, use the price at 11:59PM of the previous day, in the institution's time zone.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-type)

required, string

The security type. For detailed descriptions of available types, see [Plaid API security types](https://plaid.com/docs/api/accounts/index.html.md#StandaloneAccountType-investment) .  
  

Possible values: `cash`, `derivative`, `equity`, `etf`, `fixed income`, `loan`, `mutual fund`, `other`

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-currency)

string

The ISO 4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OptionSecurity-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "id": "account_5921",
  "isin": "US17275R1023",
  "name": "CISCO SYSTEMS INC",
  "symbol": "CSCO",
  "is_cash_equivalent": true,
  "current_price": "100.95",
  "current_as_of": "2018-08-28",
  "close_price": "100.95",
  "type": "cash",
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### ContractType 

Describes available contract type

**Properties**

[put](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#ContractType-put)

A put option

[call](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#ContractType-call)

A call option

\=\*=\*=\*=

#### Holding 

Instance of a held security.

**Properties**

[security\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-security-id)

required, string

The identifier of the security referenced by this holding.

[cost\_basis](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-cost-basis)

string

The total cost of acquiring this holding, inclusive of fees.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[quantity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-quantity)

required, string

The amount of the security (typically, number of shares) comprising this holding.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[lots](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-lots)

object

The tax lots constituting this holding.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-lots-id)

string

The unique and permanent identifier for this lot.

[acquired\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-lots-acquired-at)

string

The date at which the lot was acquired.  
  

Format: `date`

[acquired\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-lots-acquired-price)

string

The total price at which this lot was acquired.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[quantity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-lots-quantity)

string

The quantity held in this lot.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Holding-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "security_id": "string",
  "cost_basis": "100.95",
  "quantity": "100.95",
  "lots": {
    "id": "string",
    "acquired_at": "2018-08-28",
    "acquired_price": "100.95",
    "quantity": "100.95"
  },
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### TaxLot 

Describes taxable lots of shares within a Holding.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxLot-id)

required, string

The unique and permanent identifier for this lot.

[acquired\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxLot-acquired-at)

required, string

The date at which the lot was acquired.  
  

Format: `date`

[acquired\_price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxLot-acquired-price)

required, string

The total price at which this lot was acquired.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[quantity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxLot-quantity)

required, string

The quantity held in this lot.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

```json
{
  "id": "string",
  "acquired_at": "2018-08-28",
  "acquired_price": "100.95",
  "quantity": "100.95"
}
```

\=\*=\*=\*=

#### LoanAccount 

Representation of short and long-term debt.

**Properties**

[account\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-account-number)

string

The account number for this loan.

[reference\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-reference-number)

string

The loan's reference number.

[servicer\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-servicer-identity-id)

string

Reference to the identity of the loan servicer.

[interest\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-interest-rate)

required, string

The current interest rate for this loan.  
  

Pattern: `^\d*(\.\d{1,4})?$`

[interest\_rate\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-interest-rate-type)

required, string

The interest rate adjustment scheme for this loan.  
  

Possible values: `fixed`, `adjustable`, `variable`, `other`

[interest\_rate\_schedule](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-interest-rate-schedule)

\[object\]

A history of effective rates on this loan. For adjustable rate loans, include dates of future adjustments. Do not use to describe fixed-rate loans.

[start\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-interest-rate-schedule-start-date)

string

The date this rate became, or becomes, effective.  
  

Format: `date`

[end\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-interest-rate-schedule-end-date)

string

The date this rate became, or becomes, ineffective. Use `null` if the end date is not known or not fixed.  
  

Format: `date`

[interest\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-interest-rate-schedule-interest-rate)

string

The effective rate during the period described.  
  

Pattern: `^\d*(\.\d{1,4})?$`

[term\_months](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-term-months)

integer

The full length of the loan's term, in months.  
  

Minimum: `0`

[term\_days](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-term-days)

integer

The full length of the loan's term, in days.  
  

Minimum: `0`

[repayment\_status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-repayment-status)

required, string

The loan's repayment status.  
  

Possible values: `fully repaid`, `current`, `grace`, `deferment`, `forbearance`, `past due`, `delinquent`, `default`, `charged off`, `cancelled`

[principal\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-principal-balance)

required, string

The loan's remaining principal.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payoff\_quote](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-payoff-quote)

string

The instantaneous payoff quote.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payoff\_expiry](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-payoff-expiry)

string

The date until which `payoff_quote` is considered current.  
  

Format: `date`

[origination\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-origination-date)

required, string

The loan's date of origination.  
  

Format: `date`

[origination\_principal](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-origination-principal)

string

The original principal balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[maturity\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-maturity-date)

string

The loan's date of maturity.  
  

Format: `date`

[statements](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements)

\[object\]

Must describe statement periods for the account's entire history.

[payment\_paid\_to\_principal](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-payment-paid-to-principal)

string

The amount of the payment paid to principal.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payment\_paid\_to\_interest](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-payment-paid-to-interest)

string

The amount of the payment paid to interest.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[open\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-open-date)

string

The opening date of this statement period.  
  

Format: `date`

[close\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-close-date)

string

The closing date of this statement period. Use a future date if the statement period has not closed.  
  

Format: `date`

[balance\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-balance-due)

string

The statement balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[minimum\_payment\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-minimum-payment-due)

string

The minimum payment due on this statement. If the statement is paid, this should be 0.00.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payment\_due\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-payment-due-date)

string

The date payment is, or was, due for this statement.  
  

Format: `date`

[payment\_received\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-payment-received-date)

string

The date payment was received. If multiple payments were made during the period, count the date that `payment_received_amount` exceeded `minimum_payment_due`.  
  

Format: `date`

[payment\_received\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-payment-received-amount)

string

The sum of all payments received during the period.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[document\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-statements-document-url)

string

A URL to a downloadable document form of this statement. Implementers should not assume that accessors of this URL are always authorized.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "type": "loan",
  "account_number": "string",
  "reference_number": "string",
  "servicer_identity_id": "string",
  "interest_rate": "0.0199",
  "interest_rate_type": "fixed",
  "interest_rate_schedule": [
    {
      "start_date": "2018-08-28",
      "end_date": "2018-08-28",
      "interest_rate": "0.0199"
    }
  ],
  "term_months": 0,
  "term_days": 0,
  "repayment_status": "fully repaid",
  "principal_balance": "100.95",
  "payoff_quote": "100.95",
  "payoff_expiry": "2018-08-28",
  "origination_date": "2018-08-28",
  "origination_principal": "100.95",
  "maturity_date": "2018-08-28",
  "statements": [
    {
      "payment_paid_to_principal": "100.95",
      "payment_paid_to_interest": "100.95",
      "open_date": "2018-08-28",
      "close_date": "2018-08-28",
      "balance_due": "100.95",
      "minimum_payment_due": "100.95",
      "payment_due_date": "2018-08-28",
      "payment_received_date": "2018-08-28",
      "payment_received_amount": "100.95",
      "document_url": "string"
    }
  ],
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "non_owner_identity_ids": null,
  "status": "active",
  "subtype": "consumer",
  "name": "Vacation Money",
  "official_name": "Pro Checking",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "current_balance": "850.55",
  "available_balance": "149.45",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### LoanStatement 

Description of a loan account statement.

**Properties**

[payment\_paid\_to\_principal](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-payment-paid-to-principal)

string

The amount of the payment paid to principal.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payment\_paid\_to\_interest](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-payment-paid-to-interest)

string

The amount of the payment paid to interest.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[open\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-open-date)

required, string

The opening date of this statement period.  
  

Format: `date`

[close\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-close-date)

required, string

The closing date of this statement period. Use a future date if the statement period has not closed.  
  

Format: `date`

[balance\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-balance-due)

required, string

The statement balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[minimum\_payment\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-minimum-payment-due)

required, string

The minimum payment due on this statement. If the statement is paid, this should be 0.00.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payment\_due\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-payment-due-date)

required, string

The date payment is, or was, due for this statement.  
  

Format: `date`

[payment\_received\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-payment-received-date)

required, string

The date payment was received. If multiple payments were made during the period, count the date that `payment_received_amount` exceeded `minimum_payment_due`.  
  

Format: `date`

[payment\_received\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-payment-received-amount)

required, string

The sum of all payments received during the period.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[document\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanStatement-document-url)

string

A URL to a downloadable document form of this statement. Implementers should not assume that accessors of this URL are always authorized.

```json
{
  "open_date": "2018-08-28",
  "close_date": "2018-08-28",
  "balance_due": "100.95",
  "minimum_payment_due": "100.95",
  "payment_due_date": "2018-08-28",
  "payment_received_date": "2018-08-28",
  "payment_received_amount": "100.95",
  "document_url": "string"
}
```

\=\*=\*=\*=

#### InterestRateType 

Interest rate adjustment schemes.

**Properties**

[fixed](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRateType-fixed)

string

fixed rate.

[adjustable](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRateType-adjustable)

string

Adjustable rate.

[variable](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRateType-variable)

string

Variable rate.

[other](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRateType-other)

string

All other rate adjustment schemes.

\=\*=\*=\*=

#### InterestRatePeriod 

Time-bound description of interest rates and their effective periods.

**Properties**

[start\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRatePeriod-start-date)

required, string

The date this rate became, or becomes, effective.  
  

Format: `date`

[end\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRatePeriod-end-date)

required, string

The date this rate became, or becomes, ineffective. Use `null` if the end date is not known or not fixed.  
  

Format: `date`

[interest\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InterestRatePeriod-interest-rate)

required, string

The effective rate during the period described.  
  

Pattern: `^\d*(\.\d{1,4})?$`

```json
{
  "start_date": "2018-08-28",
  "end_date": "2018-08-28",
  "interest_rate": "0.0199"
}
```

\=\*=\*=\*=

#### LoanRepaymentStatus 

Loan repayment status.

**Properties**

[fully repaid](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-fully%20repaid)

string

The loan is fully repaid.

[current](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-current)

string

The loan is current and the borrow is in good standing with respect to this loan.

[grace](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-grace)

string

Loan payments have not begun, and interest is not accruing.

[deferment](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-deferment)

string

Loan payments are reduced or suspended, and interest is not accruing.

[forbearance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-forbearance)

string

Loan payments are reduced or suspended, but deferred interest is accruing.

[past due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-past%20due)

string

The borrower is past due, but can return the account to current.

[delinquent](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-delinquent)

string

The borrower is severely past due and the institution may begin Dunning.

[default](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-default)

string

The borrower has defaulted and the institution may be pursuing other remedies.

[charged off](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-charged%20off)

string

The borrower has defaulted and the institution has completed actions in connection with the default.

[cancelled](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanRepaymentStatus-cancelled)

string

The lender has cancelled this loan (use also for forgiven or discharged loans).

\=\*=\*=\*=

#### MortgageAccount 

Representation of a home mortgage loan.

**Properties**

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[escrow\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-escrow-balance)

string

The total amount held in escrow for this loan, if applicable.  
Fixed-point decimal number, carried up to six decimal places.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MortgageAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "subtype": "mortgage",
  "escrow_balance": "100.95",
  "type": "loan",
  "account_number": "string",
  "reference_number": "string",
  "servicer_identity_id": "string",
  "interest_rate": "0.0199",
  "interest_rate_type": "fixed",
  "interest_rate_schedule": [
    {
      "start_date": "2018-08-28",
      "end_date": "2018-08-28",
      "interest_rate": "0.0199"
    }
  ],
  "term_months": 0,
  "term_days": 0,
  "repayment_status": "fully repaid",
  "principal_balance": "100.95",
  "payoff_quote": "100.95",
  "payoff_expiry": "2018-08-28",
  "origination_date": "2018-08-28",
  "origination_principal": "100.95",
  "maturity_date": "2018-08-28",
  "statements": [
    {
      "payment_paid_to_principal": "100.95",
      "payment_paid_to_interest": "100.95",
      "open_date": "2018-08-28",
      "close_date": "2018-08-28",
      "balance_due": "100.95",
      "minimum_payment_due": "100.95",
      "payment_due_date": "2018-08-28",
      "payment_received_date": "2018-08-28",
      "payment_received_amount": "100.95",
      "document_url": "string"
    }
  ],
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "non_owner_identity_ids": null,
  "status": "active",
  "name": "Vacation Money",
  "official_name": "Pro Checking",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "current_balance": "850.55",
  "available_balance": "149.45",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### StudentLoanAccount 

Representational of a loan account that is specific to student loans

**Properties**

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[disbursement\_schedule](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-disbursement-schedule)

\[object\]

The schedule for disbursement of funds.

[disbursement\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-disbursement-schedule-disbursement-date)

string

The date of disbursement.  
  

Format: `date`

[amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-disbursement-schedule-amount)

string

The amount disbursed.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[guarantor\_identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity)

object

The company or agency guaranteeing the loan.

[organization](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization)

object

Describes an organization, e.g., a business or non-profit.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-name)

string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-organization-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[person](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person)

object

Describes an individual, named person.

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-first-name)

string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-middle-name)

string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-last-name)

string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-person-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-email)

string

The email address where this entity can be contacted.

[mailing\_address](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address)

object

Description of a street address.

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address-lines)

\[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address-city)

string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address-country)

string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-mailing-address-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-id)

string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-guarantor-identity-name)

string

The display name of this entity (insufficient for KYC purposes)

[pslf\_eligibility](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-pslf-eligibility)

object

Description of the loan's eligibility for public service forgiveness.

[eligible](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-pslf-eligibility-eligible)

boolean

Indicates the loan's eligibility for PSLF.

[qualifying\_payments](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-pslf-eligibility-qualifying-payments)

integer

The number of payments made which qualify under PSLF.  
  

Minimum: `0`

[total\_payments](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-pslf-eligibility-total-payments)

integer

Total payments required for forgiveness.  
  

Minimum: `0`

[sequence\_number](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-sequence-number)

string

The loan's sequence number.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#StudentLoanAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "subtype": "student",
  "disbursement_schedule": [
    {
      "disbursement_date": "2018-08-28",
      "amount": "100.95"
    }
  ],
  "guarantor_identity": {
    "organization": {
      "name": "Doe Business, Inc.",
      "structure": "sole",
      "mcc": "5542",
      "owner_identity_ids": [
        "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
      ],
      "tax_identifier": {
        "tax_authority": "IRS",
        "tax_payer_id": "string"
      }
    },
    "person": {
      "first_name": "Jane",
      "middle_name": "Joan",
      "last_name": "Doe",
      "date_of_birth": "1987-01-31",
      "tax_identifier": {
        "tax_authority": "IRS",
        "tax_payer_id": "string"
      }
    },
    "email": "jane@plaid.com",
    "mailing_address": {
      "lines": [
        "413 Leeward Way",
        "Apt 3A"
      ],
      "city": "San Francisco",
      "region": "US-CA",
      "country": "US",
      "postal_code": "94106",
      "phone": "+1 415 555 1212"
    },
    "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
    "name": "Jane Doe"
  },
  "pslf_eligibility": {
    "eligible": true,
    "qualifying_payments": 0,
    "total_payments": 0
  },
  "sequence_number": "string",
  "type": "loan",
  "account_number": "string",
  "reference_number": "string",
  "servicer_identity_id": "string",
  "interest_rate": "0.0199",
  "interest_rate_type": "fixed",
  "interest_rate_schedule": [
    {
      "start_date": "2018-08-28",
      "end_date": "2018-08-28",
      "interest_rate": "0.0199"
    }
  ],
  "term_months": 0,
  "term_days": 0,
  "repayment_status": "fully repaid",
  "principal_balance": "100.95",
  "payoff_quote": "100.95",
  "payoff_expiry": "2018-08-28",
  "origination_date": "2018-08-28",
  "origination_principal": "100.95",
  "maturity_date": "2018-08-28",
  "statements": [
    {
      "payment_paid_to_principal": "100.95",
      "payment_paid_to_interest": "100.95",
      "open_date": "2018-08-28",
      "close_date": "2018-08-28",
      "balance_due": "100.95",
      "minimum_payment_due": "100.95",
      "payment_due_date": "2018-08-28",
      "payment_received_date": "2018-08-28",
      "payment_received_amount": "100.95",
      "document_url": "string"
    }
  ],
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "non_owner_identity_ids": null,
  "status": "active",
  "name": "Vacation Money",
  "official_name": "Pro Checking",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "current_balance": "850.55",
  "available_balance": "149.45",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### Disbursement 

Description of a loan (typically student loan) disbursement event.

**Properties**

[disbursement\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Disbursement-disbursement-date)

required, string

The date of disbursement.  
  

Format: `date`

[amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Disbursement-amount)

required, string

The amount disbursed.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

```json
{
  "disbursement_date": "2018-08-28",
  "amount": "100.95"
}
```

\=\*=\*=\*=

#### PslfEligibility 

Student loan [PSLF](https://studentaid.gov/manage-loans/forgiveness-cancellation/public-service) eligibility status information.

**Properties**

[eligible](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PslfEligibility-eligible)

required, boolean

Indicates the loan's eligibility for PSLF.

[qualifying\_payments](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PslfEligibility-qualifying-payments)

integer

The number of payments made which qualify under PSLF.  
  

Minimum: `0`

[total\_payments](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PslfEligibility-total-payments)

integer

Total payments required for forgiveness.  
  

Minimum: `0`

```json
{
  "eligible": true,
  "qualifying_payments": 0,
  "total_payments": 0
}
```

\=\*=\*=\*=

#### CreditCardAccount 

Representation of
 credit card.

**Properties**

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-type)

required, string

Major classification of this account.  
  

Possible values: `depository`, `loan`, `investment`

[subtype](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-subtype)

required, string

Minor classification of this account.  
  

Possible values: `cash management`, `cd`, `checking`, `savings`, `money market`, `health`, `prepaid`, `gic`, `auto`, `commercial`, `construction`, `consumer`, `credit card`, `home equity`, `mortgage`, `overdraft`, `line of credit`, `student`, `401a`, `401k`, `403B`, `457b`, `529`, `brokerage`, `esa`, `ira`, `isa`, `lira`, `other`, `rif`, `rsp`, `pension`, `profit-sharing`, `roth ira`, `roth 401k`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `tsp`, `tfsa`, `custodial`, `variable annuity`

[current\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-current-balance)

required, string

The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[available\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-available-balance)

required, string

The immediately available balance in the account, typically the amount available to withdraw at the moment.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[reward\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-reward-balance)

string

The balance of any rewards associated with this account.  
Fixed-point decimal number, carried up to six decimal places.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[credit\_limit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-credit-limit)

required, string

The total credit limit for this account. If card has no limit, use `null`.  
Fixed-point decimal number, carried up to six decimal places.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[spender\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-spender-identity-ids)

\[string\]

References to the Identities for non-owner authorized spenders.

[interest\_rates](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates)

\[object\]

Effective interest rates for different balances associated with this card.

[start\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates-start-date)

string

The date this rate came into effect, typical of special offer rates, e.g. 0% purchase rate for 12 months. Use `start_date` and `end_date` to represent changes in the purchase APR as well.  
  

Format: `date`

[end\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates-end-date)

string

The date this rate ends being effective for this rate type. Use `null` when the rate does not have a set end date.  
  

Format: `date`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates-type)

string

The type of balance subject to this rate.  
  

Possible values: `purchase`, `cash advance`, `balance transfer`

[interest\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates-interest-rate)

string

The APR covering this balance.  
  

Pattern: `^\d*(\.\d{1,4})?$`

[subject\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates-subject-balance)

string

The current balance subject to this rate, following the definition of `current_balance`.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[interest\_charged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-interest-rates-interest-charged)

string

The amount within the `subject_balance` that was generated by this interest rate.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[statements](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements)

\[object\]

Must describe statement periods for previous two years.

[open\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-open-date)

string

The opening date of this statement period.  
  

Format: `date`

[close\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-close-date)

string

The closing date of this statement period. Use a future date if the statement period has not closed.  
  

Format: `date`

[balance\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-balance-due)

string

The statement balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[minimum\_payment\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-minimum-payment-due)

string

The minimum payment due on this statement. If the statement is paid, this should be 0.00.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payment\_due\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-payment-due-date)

string

The date payment is, or was, due for this statement.  
  

Format: `date`

[payment\_received\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-payment-received-date)

string

The date payment was received. If multiple payments were made during the period, count the date that `payment_received_amount` exceeded `minimum_payment_due`.  
  

Format: `date`

[payment\_received\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-payment-received-amount)

string

The sum of all payments received during the period.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[document\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-statements-document-url)

string

A URL to a downloadable document form of this statement. Implementers should not assume that accessors of this URL are always authorized.

[reward\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-reward-currency)

string

The ISO-4217 currency in which this account's reward balances are denominated

[reward\_non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-reward-non-iso-currency)

string

If the account's reward balance is denominated in a non-ISO currency, provide the currency's symbol

[art\_asset\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-art-asset-url)

string

URL reference to an image of the payment card face.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-id)

required, string

Permanent account identifier. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[last\_activity\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-last-activity-at)

string

Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.  
  

Format: `date-time`

[ownership\_type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-ownership-type)

string

Indicates the ownership type of the account, _not_ the relationship the current user has over the account.  
  

Possible values: `individual`, `joint`, `association`, `trust`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-owner-identity-ids)

required, \[string\]

References to the identities for the owner(s) of this account.

[non\_owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-non-owner-identity-ids)

\[string\]

References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-status)

required, string

Status of this account.  
  

Possible values: `active`, `inactive`, `frozen`, `locked`, `flagged`, `restricted`, `closed`

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-name)

string

The account's user-given name, if the institution supports naming of accounts.

[official\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-official-name)

required, string

The account's marketing or brand name.

[display\_mask](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-display-mask)

required, string

A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.

[opening\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-opening-date)

string

The date on which the account was opened.  
  

Format: `date`

[tax\_advantaged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-tax-advantaged)

boolean

Indicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-currency)

string

The ISO-4217 currency in which this account’s transactions and balances are denominated.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardAccount-non-iso-currency)

string

If the account is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "type": "loan",
  "subtype": "credit card",
  "current_balance": "850.55",
  "available_balance": "149.45",
  "reward_balance": "100.95",
  "credit_limit": "1000",
  "spender_identity_ids": [
    "string"
  ],
  "interest_rates": [
    {
      "start_date": "2018-08-28",
      "end_date": "2018-08-28",
      "type": "purchase",
      "interest_rate": "0.0199",
      "subject_balance": "100.95",
      "interest_charged": "100.95"
    }
  ],
  "statements": [
    {
      "open_date": "2018-08-28",
      "close_date": "2018-08-28",
      "balance_due": "100.95",
      "minimum_payment_due": "100.95",
      "payment_due_date": "2018-08-28",
      "payment_received_date": "2018-08-28",
      "payment_received_amount": "100.95",
      "document_url": "string"
    }
  ],
  "reward_currency": "USD",
  "reward_non_iso_currency": null,
  "art_asset_url": "string",
  "id": "R13oiR6lC5jNC5jK",
  "last_activity_at": "2020-04-21T12:45:00+00:00",
  "ownership_type": "individual",
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "non_owner_identity_ids": null,
  "status": "active",
  "name": "Vacation Money",
  "official_name": "Pro Checking",
  "display_mask": "9833",
  "opening_date": "2018-01-31",
  "tax_advantaged": true,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### CreditCardStatement 

Description of a credit card account statement.

**Properties**

[open\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-open-date)

required, string

The opening date of this statement period.  
  

Format: `date`

[close\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-close-date)

required, string

The closing date of this statement period. Use a future date if the statement period has not closed.  
  

Format: `date`

[balance\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-balance-due)

required, string

The statement balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[minimum\_payment\_due](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-minimum-payment-due)

required, string

The minimum payment due on this statement. If the statement is paid, this should be 0.00.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[payment\_due\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-payment-due-date)

required, string

The date payment is, or was, due for this statement.  
  

Format: `date`

[payment\_received\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-payment-received-date)

required, string

The date payment was received. If multiple payments were made during the period, count the date that `payment_received_amount` exceeded `minimum_payment_due`.  
  

Format: `date`

[payment\_received\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-payment-received-amount)

required, string

The sum of all payments received during the period.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[document\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardStatement-document-url)

string

A URL to a downloadable document form of this statement. Implementers should not assume that accessors of this URL are always authorized.

```json
{
  "open_date": "2018-08-28",
  "close_date": "2018-08-28",
  "balance_due": "100.95",
  "minimum_payment_due": "100.95",
  "payment_due_date": "2018-08-28",
  "payment_received_date": "2018-08-28",
  "payment_received_amount": "100.95",
  "document_url": "string"
}
```

\=\*=\*=\*=

#### CreditCardInterestRate 

Description of a credit card interest rate.

**Properties**

[start\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRate-start-date)

required, string

The date this rate came into effect, typical of special offer rates, e.g. 0% purchase rate for 12 months. Use `start_date` and `end_date` to represent changes in the purchase APR as well.  
  

Format: `date`

[end\_date](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRate-end-date)

required, string

The date this rate ends being effective for this rate type. Use `null` when the rate does not have a set end date.  
  

Format: `date`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRate-type)

required, string

The type of balance subject to this rate.  
  

Possible values: `purchase`, `cash advance`, `balance transfer`

[interest\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRate-interest-rate)

required, string

The APR covering this balance.  
  

Pattern: `^\d*(\.\d{1,4})?$`

[subject\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRate-subject-balance)

required, string

The current balance subject to this rate, following the definition of `current_balance`.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[interest\_charged](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRate-interest-charged)

required, string

The amount within the `subject_balance` that was generated by this interest rate.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

```json
{
  "start_date": "2018-08-28",
  "end_date": "2018-08-28",
  "type": "purchase",
  "interest_rate": "0.0199",
  "subject_balance": "100.95",
  "interest_charged": "100.95"
}
```

\=\*=\*=\*=

#### CreditCardInterestRateType 

Describes a type of interest rate covering a credit card balance.

**Properties**

[purchase](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRateType-purchase)

string

Purchases.

[cash advance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRateType-cash%20advance)

string

Cash advances.

[balance transfer](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#CreditCardInterestRateType-balance%20transfer)

string

Balance transfers (not payments).

Identity 
---------

\=\*=\*=\*=

#### BasicIdentity 

A lightweight identity container suitable for passing minimal identification.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BasicIdentity-id)

required, string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BasicIdentity-name)

required, string

The display name of this entity (insufficient for KYC purposes)

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BasicIdentity-email)

string

The email address where this entity can be contacted.

```json
{
  "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
  "name": "Jane Doe",
  "email": "jane@plaid.com"
}
```

\=\*=\*=\*=

#### FullIdentity 

Full identity container compatible with most PII-exchange use cases.

**Properties**

[organization](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization)

object

Describes an organization, e.g., a business or non-profit.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-name)

string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-organization-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[person](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person)

object

Describes an individual, named person.

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-first-name)

string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-middle-name)

string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-last-name)

string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-person-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

[email](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-email)

required, string

The email address where this entity can be contacted.

[mailing\_address](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address)

object

Description of a street address.

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address-lines)

\[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address-city)

string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address-country)

string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-mailing-address-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-id)

required, string

Permanent identity identifier.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#FullIdentity-name)

required, string

The display name of this entity (insufficient for KYC purposes)

```json
{
  "organization": {
    "name": "Doe Business, Inc.",
    "structure": "sole",
    "mcc": "5542",
    "owner_identity_ids": [
      "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
    ],
    "tax_identifier": {
      "tax_authority": "IRS",
      "tax_payer_id": "string"
    }
  },
  "person": {
    "first_name": "Jane",
    "middle_name": "Joan",
    "last_name": "Doe",
    "date_of_birth": "1987-01-31",
    "tax_identifier": {
      "tax_authority": "IRS",
      "tax_payer_id": "string"
    }
  },
  "email": "jane@plaid.com",
  "mailing_address": {
    "lines": [
      "413 Leeward Way",
      "Apt 3A"
    ],
    "city": "San Francisco",
    "region": "US-CA",
    "country": "US",
    "postal_code": "94106",
    "phone": "+1 415 555 1212"
  },
  "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
  "name": "Jane Doe"
}
```

\=\*=\*=\*=

#### MailingAddress 

Description of a street address.

**Properties**

[lines](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MailingAddress-lines)

required, \[string\]

The lines of the street address.  
  

Min items: `1`

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MailingAddress-city)

required, string

The city of the mailing address.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MailingAddress-region)

string

The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MailingAddress-country)

required, string

The ISO 3166-alpha-2 country code.

[postal\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MailingAddress-postal-code)

string

The postal code.

[phone](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#MailingAddress-phone)

string

The phone number, formatted using [ITU standard E. 123](https://www.wikiwand.com/en/E.123) .

```json
{
  "lines": [
    "413 Leeward Way",
    "Apt 3A"
  ],
  "city": "San Francisco",
  "region": "US-CA",
  "country": "US",
  "postal_code": "94106",
  "phone": "+1 415 555 1212"
}
```

\=\*=\*=\*=

#### PersonalEntity 

Describes an individual, named person.

**Properties**

[first\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-first-name)

required, string

Legal given name of the personal entity.

[middle\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-middle-name)

required, string

Middle name, use blank if none.

[last\_name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-last-name)

required, string

Last name or family name.

[date\_of\_birth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-date-of-birth)

string

The date of birth in ISO-8601 format.  
  

Format: `date`

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PersonalEntity-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

```json
{
  "first_name": "Jane",
  "middle_name": "Joan",
  "last_name": "Doe",
  "date_of_birth": "1987-01-31",
  "tax_identifier": {
    "tax_authority": "IRS",
    "tax_payer_id": "string"
  }
}
```

\=\*=\*=\*=

#### OrganizationalEntity 

Describes an organization, e.g., a business or non-profit.

**Properties**

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-name)

required, string

Name of the organization represented.

[structure](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-structure)

string

Type of business structure.  
  

Possible values: `sole`, `partnership`, `llc`, `corp`

[mcc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-mcc)

string

The ISO-18245 merchant category code for this business.  
  

Pattern: `^\d{4}$`

[owner\_identity\_ids](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-owner-identity-ids)

\[string\]

The identities of the organization owner(s).

[tax\_identifier](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-tax-identifier)

object

The tax authority ID.

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-tax-identifier-tax-authority)

string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-tax-identifier-tax-payer-id)

string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-tax-identifier-country)

string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#OrganizationalEntity-tax-identifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

```json
{
  "name": "Doe Business, Inc.",
  "structure": "sole",
  "mcc": 5542,
  "owner_identity_ids": [
    "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
  ],
  "tax_identifier": {
    "tax_authority": "IRS",
    "tax_payer_id": "string",
    "country": "US"
  }
}
```

\=\*=\*=\*=

#### USBusinessStructure 

Enumeration of business structures in the U.S.

**Properties**

[sole](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#USBusinessStructure-sole)

string

Sole proprietorship.

[partnership](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#USBusinessStructure-partnership)

string

Partnership, e.g. limited partnership, general partnership.

[llc](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#USBusinessStructure-llc)

string

Limited liability company.

[corp](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#USBusinessStructure-corp)

string

C-corp, S-corp, not-for-profit, etc.

\=\*=\*=\*=

#### TaxIdentifier 

Tax identifiers model an international-compliant identity within a tax authority. Use these to communicate a taxable entity’s identity within a jurisdiction.

**Properties**

[tax\_authority](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxIdentifier-tax-authority)

required, string

Name of the tax authority.

[tax\_payer\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxIdentifier-tax-payer-id)

required, string

The tax payer ID, e.g. EIN, TIN, SSN.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxIdentifier-country)

required, string

The national jurisdiction of the tax authority in ISO 3166-1 format.

[subdivision](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#TaxIdentifier-subdivision)

string

If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.

```json
{
  "tax_authority": "IRS",
  "tax_payer_id": "string",
  "country": "US",
  "subdivision": ""
}
```

Transaction 
------------

\=\*=\*=\*=

#### BaseTransaction 

Base properties for all transactions.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-id)

required, string

Permanent, unique transaction identifier. Must survive changes to pending status or amount.

[account\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-account-id)

required, string

References to the account that this transaction is posting against.

[description](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-description)

required, string

Description of the transaction.  
Nullable: true

[memo](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-memo)

string

Addenda or distinguishing information for the transaction.

[category](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-category)

\[string\]

Hierarchical categorization, use multi-valued array to indicate hierarchy.

[tags](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-tags)

\[string\]

Flat categorization. For hashtags omit leading `#`.

[ending\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-ending-balance)

string

The balance of the account after this transaction posts.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[transacted\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-transacted-at)

required, string

The date/time when the transaction was authorized, in the time zone local to the transaction or to the customer.  
  

Format: `date-time`

[settled\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-settled-at)

required, string

The date/time when the transaction settled, in the time zone local to the customer. Must be `null` if the transaction is pending.  
Nullable: true  
  

Format: `date-time`

[spender\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-spender-identity-id)

string

Reference to the identity of the authorized spender who conducted this transaction.

[merchant\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-merchant-identity-id)

string

Reference to the identity of the merchant related to this transaction.

[geolocation](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation)

object

Geographic location where this transaction occurs.

[coordinates](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation-coordinates)

object

Geographic coordinates in [EPSG:4326 WGS84](https://epsg.io/4326) (lat/long)

[lat](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation-coordinates-lat)

number

Latitude coordinate.

[lon](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation-coordinates-lon)

number

Longitude coordinate.

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation-city)

string

City name.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation-region)

string

Region identifier.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-geolocation-country)

string

Country identifier.

[reward\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-reward-currency)

string

The ISO 4217 currency in which this transaction's reward contribution is denominated. example: USD

[reward\_non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-reward-non-iso-currency)

string

If the reward contribution is denominated in a non-ISO currency, provide the currency's symbol.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-currency)

string

The ISO 4217 currency in which this transaction is denominated. One of either the `currency` or `non_iso_currency` fields is required.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BaseTransaction-non-iso-currency)

string

If the transaction is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "id": "6AOU0jwFQw3sMZJ",
  "account_id": 100273,
  "description": "Finance Charge",
  "memo": "Check #318",
  "category": [
    "electronics",
    "desktop",
    "accessories"
  ],
  "tags": [
    "electronics",
    "accessories"
  ],
  "ending_balance": "100.95",
  "transacted_at": "2019-08-22T14:15:22Z",
  "settled_at": "2019-08-25T08:15:42Z",
  "spender_identity_id": "uid_1234",
  "merchant_identity_id": "amazon_880",
  "geolocation": {
    "coordinates": {
      "lat": 40.7128,
      "lon": 74.006
    },
    "city": "New York",
    "region": "US-NY",
    "country": "US"
  },
  "reward_non_iso_currency": null,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### DepositoryOrCreditTransaction 

Describes a transaction against a depository or credit card account.

**Properties**

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-type)

string

Classification of `DepositoryOrCreditTransaction` by purpose as an enum. `transfer`: A transfer between accounts, or balance transfer (for credit cards). `cash`: Cash withdrawal, or cash advance (for credit cards) including check drafts. `fee`: Finance charges, or fees associated with account management, e.g. ATM fees, overdraft charges, etc. `purchase`: Ordinary purchase activity, subject to the purchase APR (for credit cards). `interest`: Interest earned, not finance charges on carried balance (use fee). `deposit`: Cash or electronic deposit from an external account, not a transfer; or a payment (for credit cards).  
  

Possible values: `transfer`, `cash`, `fee`, `purchase`, `interest`, `deposit`

[pending](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-pending)

required, boolean

Indicates that this transaction has not posted.

[amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-amount)

required, string

The amount of the transaction. Use a positive amount for transactions where money is flowing out of the account, and a negative amount for those where money flows into the account.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[fee\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-fee-amount)

string

The amount of fees associated with this transaction.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[reward\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-reward-amount)

string

The amount of rewards associated with this transaction.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[reward\_rate](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-reward-rate)

string

The effective rate of reward for this transaction.  
  

Pattern: `^\d*(\.\d{1,4})?$`

[transfer\_account\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-transfer-account-id)

string

If this transaction is an internal transfer type, references the `account_id` associated with this transaction.

[method](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-method)

string

Classification of `DepositoryOrCreditTransaction` by method. `card present`: Transaction was conducted by a physical payment card interaction (e.g. swipe, chip-and-sign, contactless). `card not present`: Card was not physically present for transaction (e.g. online or phone order). `check`: Check drafted against account. `eft`: Electronic funds transfer.  
  

Possible values: `card present`, `card not present`, `check`, `eft`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-id)

required, string

Permanent, unique transaction identifier. Must survive changes to pending status or amount.

[account\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-account-id)

required, string

References to the account that this transaction is posting against.

[description](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-description)

required, string

Description of the transaction.  
Nullable: true

[memo](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-memo)

string

Addenda or distinguishing information for the transaction.

[category](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-category)

\[string\]

Hierarchical categorization, use multi-valued array to indicate hierarchy.

[tags](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-tags)

\[string\]

Flat categorization. For hashtags omit leading `#`.

[ending\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-ending-balance)

string

The balance of the account after this transaction posts.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[transacted\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-transacted-at)

required, string

The date/time when the transaction was authorized, in the time zone local to the transaction or to the customer.  
  

Format: `date-time`

[settled\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-settled-at)

required, string

The date/time when the transaction settled, in the time zone local to the customer. Must be `null` if the transaction is pending.  
Nullable: true  
  

Format: `date-time`

[spender\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-spender-identity-id)

string

Reference to the identity of the authorized spender who conducted this transaction.

[merchant\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-merchant-identity-id)

string

Reference to the identity of the merchant related to this transaction.

[geolocation](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation)

object

Geographic location where this transaction occurs.

[coordinates](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation-coordinates)

object

Geographic coordinates in [EPSG:4326 WGS84](https://epsg.io/4326) (lat/long)

[lat](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation-coordinates-lat)

number

Latitude coordinate.

[lon](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation-coordinates-lon)

number

Longitude coordinate.

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation-city)

string

City name.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation-region)

string

Region identifier.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-geolocation-country)

string

Country identifier.

[reward\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-reward-currency)

string

The ISO 4217 currency in which this transaction's reward contribution is denominated. example: USD

[reward\_non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-reward-non-iso-currency)

string

If the reward contribution is denominated in a non-ISO currency, provide the currency's symbol.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-currency)

string

The ISO 4217 currency in which this transaction is denominated. One of either the `currency` or `non_iso_currency` fields is required.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransaction-non-iso-currency)

string

If the transaction is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "type": "purchase",
  "pending": false,
  "amount": "100.95",
  "fee_amount": "0",
  "reward_amount": "2.01",
  "reward_rate": "0.0199",
  "transfer_account_id": null,
  "method": "card present",
  "id": "6AOU0jwFQw3sMZJ",
  "account_id": "account1234",
  "description": "Finance Charge",
  "memo": "Check #318",
  "category": [
    "grocery",
    "meat"
  ],
  "tags": [
    "grocery"
  ],
  "ending_balance": "100.95",
  "transacted_at": "2019-08-24T14:15:22Z",
  "settled_at": "2019-08-25T08:45:03Z",
  "spender_identity_id": "uid_1234",
  "merchant_identity_id": "target",
  "geolocation": {
    "coordinates": {
      "lat": 40.7128,
      "lon": 74.006
    },
    "city": "New York",
    "region": "US-NY",
    "country": "US"
  },
  "reward_currency": "USD",
  "reward_non_iso_currency": null,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### DepositoryOrCreditTransactionType 

Classification of `DepositoryOrCreditTransaction` by purpose as an enum.

**Properties**

[transfer](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionTypeTableForDocs-transfer)

string

A transfer between accounts, or balance transfer (for credit cards).

[cash](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionTypeTableForDocs-cash)

string

Cash withdrawal, or cash advance (for credit cards) including check drafts.

[fee](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionTypeTableForDocs-fee)

string

Finance charges, or fees associated with account management, e.g. ATM fees, overdraft charges, etc.

[purchase](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionTypeTableForDocs-purchase)

string

Ordinary purchase activity, subject to the purchase APR (for credit cards).

[interest](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionTypeTableForDocs-interest)

string

Interest earned, not finance charges on carried balance (use fee).

[deposit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionTypeTableForDocs-deposit)

string

Cash or electronic deposit from an external account, not a transfer; or a payment (for credit cards).

\=\*=\*=\*=

#### DepositoryOrCreditTransactionMethod 

Classification of `DepositoryOrCreditTransaction` by method.

**Properties**

[card present](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionMethodTableForDocs-card%20present)

string

Transaction was conducted by a physical payment card interaction (e.g. swipe, chip-and-sign, contactless).

[card not present](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionMethodTableForDocs-card%20not%20present)

string

Card was not physically present for transaction (e.g. online or phone order).

[check](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionMethodTableForDocs-check)

string

Check drafted against account.

[eft](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#DepositoryOrCreditTransactionMethodTableForDocs-eft)

string

Electronic funds transfer.

\=\*=\*=\*=

#### InvestmentTransaction 

Describes a transaction in an investment account.

**Properties**

[amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-amount)

required, string

The amount associated with this transaction. Should be the product of price and quantity, plus fees.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-type)

required, string

Classification of `InvestmentTransaction` by purpose. Values: `buy`: Activity increasing the quantity of a holding. `sell`: Activity decreasing the quantity of a holding. `cash`: Activity modifying the account’s cash position. `fee`: Fees on the account, e.g. commission, bookkeeping, options-related charges. `transfer`: Activity which modifies a position, outside of buying/selling activity e.g., options exercise, portfolio transfer. `purchase`: Ordinary purchase activity, subject to the purchase APR (for credit cards). `interest`: Interest earned, not finance charges on carried balance (use fee). `deposit`: Cash or electronic deposit from an external account, not a transfer; or a payment (for credit cards).  
  

Possible values: `buy`, `sell`, `cash`, `fee`, `transfer`, `purchase`, `interest`, `deposit`

[security\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-security-id)

required, string

Reference to the security that the transaction is posting for.

[quantity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-quantity)

required, string

The quantity of the security involved in this transaction.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[price](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-price)

required, string

The price of the security at which the transaction occured.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[fees](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-fees)

string

The total combined fees associated with this transaction.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[status](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-status)

required, string

Status of an `InvestmentTransaction`. `pending`: The trade is in progress, or transfer is pending. `settled`: The transaction has completed. `cancelled`: The transaction was cancelled, or represents the cancelled portion of a previous order.  
  

Possible values: `pending`, `settled`, `cancelled`

[cancel\_transaction\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-cancel-transaction-id)

string

If the status is `cancelled`, but this transaction represents the unfulfilled portion of a partially filled order, provide the `transaction_id` of the transaction representing the filled portion.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-id)

required, string

Permanent, unique transaction identifier. Must survive changes to pending status or amount.

[account\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-account-id)

required, string

References to the account that this transaction is posting against.

[description](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-description)

required, string

Description of the transaction.  
Nullable: true

[memo](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-memo)

string

Addenda or distinguishing information for the transaction.

[category](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-category)

\[string\]

Hierarchical categorization, use multi-valued array to indicate hierarchy.

[tags](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-tags)

\[string\]

Flat categorization. For hashtags omit leading `#`.

[ending\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-ending-balance)

string

The balance of the account after this transaction posts.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[transacted\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-transacted-at)

required, string

The date/time when the transaction was authorized, in the time zone local to the transaction or to the customer.  
  

Format: `date-time`

[settled\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-settled-at)

required, string

The date/time when the transaction settled, in the time zone local to the customer. Must be `null` if the transaction is pending.  
Nullable: true  
  

Format: `date-time`

[spender\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-spender-identity-id)

string

Reference to the identity of the authorized spender who conducted this transaction.

[merchant\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-merchant-identity-id)

string

Reference to the identity of the merchant related to this transaction.

[geolocation](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation)

object

Geographic location where this transaction occurs.

[coordinates](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation-coordinates)

object

Geographic coordinates in [EPSG:4326 WGS84](https://epsg.io/4326) (lat/long)

[lat](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation-coordinates-lat)

number

Latitude coordinate.

[lon](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation-coordinates-lon)

number

Longitude coordinate.

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation-city)

string

City name.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation-region)

string

Region identifier.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-geolocation-country)

string

Country identifier.

[reward\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-reward-currency)

string

The ISO 4217 currency in which this transaction's reward contribution is denominated. example: USD

[reward\_non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-reward-non-iso-currency)

string

If the reward contribution is denominated in a non-ISO currency, provide the currency's symbol.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-currency)

string

The ISO 4217 currency in which this transaction is denominated. One of either the `currency` or `non_iso_currency` fields is required.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransaction-non-iso-currency)

string

If the transaction is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "value": {
    "amount": "100.95",
    "type": "buy",
    "security_id": "string",
    "quantity": "100.95",
    "price": "100.95",
    "fees": "100.95",
    "status": "settled",
    "cancel_transaction_id": "string",
    "id": "6AOU0jwFQw3sMZJ",
    "account_id": "account_1234",
    "description": "Finance Charge",
    "memo": "Check #318",
    "category": [
      "electronics",
      "desktop",
      "accessories"
    ],
    "tags": [
      "electronics",
      "desktop"
    ],
    "ending_balance": "100.95",
    "transacted_at": "2019-08-24T14:15:22Z",
    "settled_at": "2019-08-25T08:15:42Z",
    "spender_identity_id": "uid_1234",
    "merchant_identity_id": null,
    "geolocation": {
      "coordinates": {
        "lat": 40.7128,
        "lon": 74.006
      },
      "city": "New York",
      "region": "US-NY",
      "country": "US"
    },
    "reward_currency": "USD",
    "reward_non_iso_currency": null,
    "currency": "USD",
    "non_iso_currency": null
  },
  "description": "Classification of `InvestmentTransaction` by purpose."
}
```

\=\*=\*=\*=

#### InvestmentTransactionType 

Classification of `InvestmentTransaction` by purpose.

**Properties**

[buy](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-buy)

string

Activity increasing the quantity of a holding.

[cash](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-cash)

string

Activity modifying the account’s cash position.

[fee](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-fee)

string

Fees on the account, e.g. commission, bookkeeping, options-related charges.

[sell](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-sell)

string

Activity decreasing the quantity of a holding.

[transfer](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-transfer)

string

Activity which modifies a position, outside of buying/selling activity e.g., options exercise, portfolio transfer.

[purchase](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-purchase)

string

Ordinary purchase activity, subject to the purchase APR (for credit cards).

[interest](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-interest)

string

Interest earned, not finance charges on carried balance (use fee).

[deposit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionTypeTableForDocs-deposit)

string

Cash or electronic deposit from an external account, not a transfer; or a payment (for credit cards).

\=\*=\*=\*=

#### InvestmentTransactionStatus 

Status of an `InvestmentTransaction`.

**Properties**

[pending](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionStatusTableForDocs-pending)

string

The trade is in progress, or transfer is pending.

[settled](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionStatusTableForDocs-settled)

string

The transaction has completed.

[cancelled](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InvestmentTransactionStatusTableForDocs-cancelled)

string

The transaction was cancelled, or represents the cancelled portion of a previous order.

\=\*=\*=\*=

#### LoanTransaction 

Describes a transaction in a loan account.

**Properties**

[amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-amount)

required, string

The amount associated with this transaction. Should be the sum of `principal_amount`, `interest_amount`, and `escrow_amount` (if present).  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[type](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-type)

string

Classification of `LoanTransaction` by purpose or effect. `payment`: The transaction describes a payment on the loan. `principal`: The transaction advances or reduces the principal. `interest`: The transaction advances or reduces interest. `adjustment`: The transaction adjusts the loan’s balances, unrelated to a loan payment.  
  

Possible values: `pending`, `settled`, `cancelled`

[principal\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-principal-amount)

required, string

The amount affecting the principal balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[interest\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-interest-amount)

required, string

The amount affecting the interest balance.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[escrow\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-escrow-amount)

string

The amount affecting the escrow account (mortgages only, required.)  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-id)

required, string

Permanent, unique transaction identifier. Must survive changes to pending status or amount.

[account\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-account-id)

required, string

References to the account that this transaction is posting against.

[description](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-description)

required, string

Description of the transaction.  
Nullable: true

[memo](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-memo)

string

Addenda or distinguishing information for the transaction.

[category](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-category)

\[string\]

Hierarchical categorization, use multi-valued array to indicate hierarchy.

[tags](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-tags)

\[string\]

Flat categorization. For hashtags omit leading `#`.

[ending\_balance](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-ending-balance)

string

The balance of the account after this transaction posts.  
  

Pattern: `^-?(\d*)(?:\.\d{1,2})?$`

[transacted\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-transacted-at)

required, string

The date/time when the transaction was authorized, in the time zone local to the transaction or to the customer.  
  

Format: `date-time`

[settled\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-settled-at)

required, string

The date/time when the transaction settled, in the time zone local to the customer. Must be `null` if the transaction is pending.  
Nullable: true  
  

Format: `date-time`

[spender\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-spender-identity-id)

string

Reference to the identity of the authorized spender who conducted this transaction.

[merchant\_identity\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-merchant-identity-id)

string

Reference to the identity of the merchant related to this transaction.

[geolocation](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation)

object

Geographic location where this transaction occurs.

[coordinates](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation-coordinates)

object

Geographic coordinates in [EPSG:4326 WGS84](https://epsg.io/4326) (lat/long)

[lat](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation-coordinates-lat)

number

Latitude coordinate.

[lon](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation-coordinates-lon)

number

Longitude coordinate.

[city](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation-city)

string

City name.

[region](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation-region)

string

Region identifier.

[country](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-geolocation-country)

string

Country identifier.

[reward\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-reward-currency)

string

The ISO 4217 currency in which this transaction's reward contribution is denominated. example: USD

[reward\_non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-reward-non-iso-currency)

string

If the reward contribution is denominated in a non-ISO currency, provide the currency's symbol.

[currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-currency)

string

The ISO 4217 currency in which this transaction is denominated. One of either the `currency` or `non_iso_currency` fields is required.

[non\_iso\_currency](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransaction-non-iso-currency)

string

If the transaction is denominated in a non-ISO currency, provide the currency's symbol.

```json
{
  "amount": "100.95",
  "type": "payment",
  "principal_amount": "100.95",
  "interest_amount": "2.95",
  "escrow_amount": "1.95",
  "id": "6AOU0jwFQw3sMZJ",
  "account_id": "account1234",
  "description": "Finance Charge",
  "memo": "Check #318",
  "category": [
    "electronics",
    "desktop",
    "accessories"
  ],
  "tags": [
    "electronics",
    "desktop"
  ],
  "ending_balance": "100.95",
  "transacted_at": "2019-08-24T14:15:22Z",
  "settled_at": "2019-08-25T08:15:42Z",
  "spender_identity_id": "uid_1234",
  "merchant_identity_id": "apex_rentals_091",
  "geolocation": {
    "coordinates": {
      "lat": 40.7128,
      "lon": 74.006
    },
    "city": "New York",
    "region": "US-NY",
    "country": "US"
  },
  "reward_currency": "USD",
  "reward_non_iso_currency": null,
  "currency": "USD",
  "non_iso_currency": null
}
```

\=\*=\*=\*=

#### LoanTransactionType 

Classification of `LoanTransaction` by purpose or effect.

**Properties**

[payment](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransactionTypeTableForDocs-payment)

string

The transaction describes a payment on the loan.

[principal](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransactionTypeTableForDocs-principal)

string

The transaction advances or reduces the principal.

[interest](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransactionTypeTableForDocs-interest)

string

The transaction advances or reduces interest.

[adjustment](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#LoanTransactionTypeTableForDocs-adjustment)

string

The transaction adjusts the loan’s balances, unrelated to a loan payment.

Acquisition 
------------

\=\*=\*=\*=

#### PlaidProductDataType 

Scope of requested account features or content for a `PlaidApplication`, represented as an enum.

**Properties**

[ACCOUNT\_BALANCE](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PlaidProductDataTypeTableForDocs-ACCOUNT-BALANCE)

string

Balance for each of the user's accounts. Used in various Plaid products, such as Auth.

[ACCOUNT\_TRANSACTIONS](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PlaidProductDataTypeTableForDocs-ACCOUNT-TRANSACTIONS)

string

Historical and current transactions for each of the user's accounts. Used in the Plaid Transactions product.

[ACCOUNT\_USER\_INFO](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PlaidProductDataTypeTableForDocs-ACCOUNT-USER-INFO)

string

User's personally identifying information, including account and routing numbers. Used in the [Plaid Identity product](https://plaid.com/products/identity) .

\=\*=\*=\*=

#### PlaidProduct 

Plaid products that a `PlaidApplication` uses.

**Properties**

[auth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PlaidProduct-auth)

string

[Auth](https://plaid.com/products/auth/) , funds transfer principals.

[identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PlaidProduct-identity)

string

[Identity](https://plaid.com/products/identity) , personally identifying information

[transactions](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#PlaidProduct-transactions)

string

[Transactions](https://plaid.com/products/transactions) , historical and current.

\=\*=\*=\*=

#### NewAccountApplicant 

Describes an application to open a new bank account.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NewAccountApplicant-id)

string

The ID of this applicant.

[identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NewAccountApplicant-identity)

string

The `FullIdentity` of the applicant.

[funding\_transfer\_code](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NewAccountApplicant-funding-transfer-code)

string

The transfer code for the funding account if applicant opts to fund the account on opening.'

[funding\_amount](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#NewAccountApplicant-funding-amount)

string

The amount to transfer into the account upon opening.

Application 
------------

\=\*=\*=\*=

#### Application 

Describes a Plaid-powered application.

**Properties**

[application\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Application-application-id)

required, string

The application’s unique ID.

[name](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Application-name)

required, string

The name of the application.

[logo](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Application-logo)

string

A URL that links to the application logo image.

[application\_url](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Application-application-url)

string

A URL that links to the application’s website.

[reason\_for\_access](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Application-reason-for-access)

string

A string provided by the connected app stating why they use their respective enabled products.

```json
{
  "application_id": "123123-123123-application_id",
  "name": "App Name",
  "logo": "https://www.plaid.com/logo",
  "application_url": "https://www.application.com",
  "reason_for_access": "Need balance"
}
```

\=\*=\*=\*=

#### ConnectedApplication 

Scope 
------

\=\*=\*=\*=

#### Scopes 

The scopes object

**Properties**

[product\_access](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-product-access)

object

Allow or disallow product access across all accounts. If unset, defaults to all products allowed.

[statements](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-product-access-statements)

boolean

Allow access to statements.  
  

Default: `true`

[identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-product-access-identity)

boolean

Allow access to the Identity product (name, email, phone, address).  
  

Default: `true`

[auth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-product-access-auth)

boolean

Allow access to account number details.  
  

Default: `true`

[transactions](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-product-access-transactions)

boolean

Allow access to transaction details.  
  

Default: `true`

[accounts](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-accounts)

array

Allow or disallow product access by account. Unlisted (e.g. missing) accounts will be considered `new_accounts`.  
  

Min items: `1`

[new\_accounts](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#Scopes-new-accounts)

boolean

Allow access to newly opened accounts as they are opened.  
  

Default: `true`

```json
{
  "product_access": {
    "identity": false,
    "statement": false,
    "auth": true,
    "transactions": false
  },
  "accounts": [
    {
      "unique_id": "915ace15f",
      "selected": true
    },
    {
      "unique_id": "1512343cc",
      "selected": true
    }
  ],
  "new_accounts": true
}
```

\=\*=\*=\*=

#### RequestedScope 

\=\*=\*=\*=

#### AccountSelectionCardinality 

The application requires that accounts be limited to a specific cardinality. Represented as an enum.

**Properties**

[enum\_values](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountSelectionCardinality-enum-values)

string

Enum values  
  

Possible values: `SINGLE_SELECT`, `MULTI_SELECT`, `ALL`

\=\*=\*=\*=

#### AccountAccess 

Allow or disallow product access by account. Unlisted (e.g. missing) accounts will be considered `new_accounts`.

**Properties**

[unique\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountAccess-unique-id)

required, string

The unique account identifier for this account. This value must match that returned by the data access API for this account. **Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).**

[authorized](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountAccess-authorized)

boolean

Allow the application to see this account (and associated details, including balance) in the list of accounts.  
  

Default: `true`

```json
{
  "unique_id": "abc1241f975",
  "authorized": true
}
```

\=\*=\*=\*=

#### AccountFilter 

Describes the account subtypes that the application wishes for the user to be able to select from. For more details please refer to Plaid documentation on account filters.

**Properties**

[depository](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-depository)

Depository subtypes required.

[subtypes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-depository-subtypes)

string

List of account subtypes.

[credit](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-credit)

AccountFilterSubtypes

Credit subtypes required.

[subtypes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-credit-subtypes)

string

List of account subtypes.

[loan](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-loan)

AccountFilterSubtypes

Loan subtypes required.

[subtypes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-loan-subtypes)

string

List of account subtypes.

[investment](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-investment)

AccountFilterSubtypes

Investment subtypes required.

[subtypes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilter-investment-subtypes)

string

List of account subtypes.

```json
{
  "depository": {
    "account_subtypes": [
      "checking",
      "savings"
    ]
  }
}
```

\=\*=\*=\*=

#### AccountFilterSubtypes 

A list of account subtypes to be filtered.

**Properties**

[subtypes](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AccountFilterSubtypes-subtypes)

string

List of account subtypes.

```json
[
  "checking",
  "savings"
]
```

\=\*=\*=\*=

#### ProductAccess 

Allow or disallow product access across all accounts. If unset, defaults to all products allowed.

**Properties**

[statements](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#ProductAccess-statements)

boolean

Allow access to statements.  
  

Default: `true`

[identity](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#ProductAccess-identity)

boolean

Allow access to the Identity product (name, email, phone, address).  
  

Default: `true`

[auth](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#ProductAccess-auth)

boolean

Allow access to account number details.  
  

Default: `true`

[transactions](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#ProductAccess-transactions)

boolean

Allow access to transaction details.  
  

Default: `true`

```json
{
  "auth": true,
  "identity": false,
  "statements": false,
  "transactions": false
}
```

Errors 
-------

\=\*=\*=\*=

#### BasicError 

Generic error object.

**Properties**

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BasicError-id)

required, string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#BasicError-message)

required, string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

```json
{
  "id": "E00001",
  "message": "string"
}
```

\=\*=\*=\*=

#### AuthenticationError 

Authentication-specific error object.

**Properties**

[reason](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AuthenticationError-reason)

required, string

Reason code for authentication failures.  
  

Possible values: `credentials`, `configuration`, `mfa`, `not permitted`, `unsupported`, `other`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AuthenticationError-id)

required, string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#AuthenticationError-message)

required, string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

```json
{
  "reason": "credentials",
  "id": "E00001",
  "message": "The submitted credentials are not valid."
}
```

\=\*=\*=\*=

#### InstitutionError 

Error schema for planned institution downtime.

**Properties**

[retry\_at](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InstitutionError-retry-at)

string

The time, in UTC, when the institution is expected to support aggregation again.  
  

Format: `date-time`

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InstitutionError-id)

required, string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md#InstitutionError-message)

required, string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

```json
{
  "retry_at": "2020-10-02T00:15:00.000+0000",
  "id": "E00001",
  "message": "string"
}
```

---


# Errors and Conditions | Plaid Docs

Errors and Exceptional Conditions 
==================================

#### Plaid Exchange error and messaging details 

Communicating errors 
---------------------

For certain predictable conditions, the implementer can return an `ErrorResponse` and use the HTTP status code to communicate the cause of the error.

### Response 

##### ErrorResponse 

Response indicating the presence of an error.

**Properties**

[request\_id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/errors-and-conditions/index.html.md#BasicErrorResponse-request-id)

string

Unique identifier useful for tracing this request, when debugging.

[error](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/errors-and-conditions/index.html.md#BasicErrorResponse-error)

required, object

Generic error object.

[id](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/errors-and-conditions/index.html.md#BasicErrorResponse-error-id)

string

Opaque identifier, expected to be consistent for errors which have the same cause.

[message](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/errors-and-conditions/index.html.md#BasicErrorResponse-error-message)

string

Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.

```json
{
  "request_id": "m8MDnv9okwxFNBV",
  "error": {
    "id": "E00001",
    "message": "string"
  }
}
```

##### 400 Bad Request 

This response should be used to indicate that the parameters to the method were incorrect, e.g., the pagination parameters were out of range, or the dates were not specified in the correct format.

##### 401 Unauthorized 

This response should be used to indicate that the request requires authentication before it can be fulfilled. It should be returned when the request does not contain the required authentication methods: either an invalid/missing authentication token, or invalid credential pair in the case of the [Authentication API Method](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/index.html.md) endpoint.

##### 503 Unavailable 

This response should be used to indicate that the institution is currently unavailable to respond to the request. The implementer may return an `InstitutionError` to indicate the time when it prefers that Plaid retries its requests.

---


# API Reference | Plaid Docs

API Reference 
==============

#### Data Definitions, Data Endpoints and Errors 

#### Data Definitions 

Plaid Exchange data definitions, objects and data types.

[Get Started](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/data-definitions/index.html.md)

#### API Reference 

Reference for building out the Plaid Exchange APIs.

[Get Started](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/aggregation/index.html.md)

#### Error Handling 

Information about handling errors inside Plaid Exchange.

[Get Started](https://plaid.comhttps://plaid.com/plaid-exchange/docs/reference/errors-and-conditions/index.html.md)

---


# User experience | Plaid Docs

User Experience 
================

#### Plaid User Experience guide 

[Plaid Link](https://plaid.com/docs/link/index.html.md) is the UI component users interact with to link their accounts to an app using Plaid. Your institution will show up in Plaid Link after you go live on Plaid Exchange.

Institution select 
-------------------

A user wants to connect their financial account to an app called WonderWallet. WonderWallet sends them to Plaid Link where they can select their financial institution. In this example, the financial institution is called First Platypus Bank.

(An image of "OAuth Example")

OAuth authentication 
---------------------

The user is asked to authenticate with First Platypus. Plaid recommends you do this using the OAuth 2.0 protocol.

You own the OAuth user experience and host it on your domain. We encourage you have two screens with your logo prominently featured: a login screen and two-step verification screen.

(An image of "OAuth Authentication Example Login Page")

App2App 
--------

If you have a native mobile application, Plaid strongly recommends enabling App2App authentication in order to enable a more secure and seamless consumer authentication experience. The example below uses an App2App flow. The user is brought to the First Platypus app to authenticate where they can use biometrics.

(An image of "App2App Example Login Page\]")

WebAuthn 
---------

We also recommend using [WebAuthn](https://webauthn.io/) for web-based authentication. Users can enroll and then easily use biometrics to authenticate on any web browser.

(An image of "WebAuthn Biometric Login Example")

Account selection 
------------------

If the user has more than one financial account, the user returns to Plaid Link and is asked to select which accounts they’d like to link. The user then sees a success screen. Tapping the continue button will return them to WonderWallet.

(An image of "Account Selection Example")

Returning user experience 
--------------------------

The returning user experience (RUX) streamlines onboarding for users who have previously connected a financial account with Plaid via your institution’s OAuth and API integration. For returning users who have been verified by Plaid, we can enable them to securely authenticate their account in fewer steps.

A user must connect their account through your OAuth flow before they are eligible for Plaid’s returning user experience. When the same user wants to connect their account to another app, Plaid enables the user to do so in a secure way via Plaid Link-based authentication methods like biometrics, One-time Passcodes, etc. This is supplemented with both internal and external security mechanisms such as browser, network, and device fingerprinting.

As a data partner for Plaid Exchange, you’re automatically enabled for RUX with no integration work required. Your eligible users can now benefit from a faster way to securely connect their accounts to apps and services on the Plaid network.

---