{"info":{"_postman_id":"841d643c-b27c-413c-8a04-e3375741c317","name":"Plaid API DOC","description":"

Plaid API is a financial tool by Plaid, a financial technology company, to enable developers to integrate users' financial data into their applications. The API allows for access to users' account information, transactions, and other financial data from thousands of financial institutions.

With the Plaid API, developers can build applications such as personal finance tools, budgeting apps, and lending platforms. The API is designed to be secure, scalable, and compliant with relevant regulations, making it a popular choice for developers building financial applications.

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, you will need a client_id and secret key. Follow the step below to get one:

create an account on the Plaid Dashboard.
\n
Click on Developers on side bar
\n
Click on Keys
\n
Copy your client_id and secreton the key page as seen below
\n

\n\n

API Protocols and Headers

The Plaid API uses JSON over HTTP. All requests are POST requests, and responses are in JSON format. Errors are shown in the response bodies as error_code and error_type. Use these instead of HTTP status codes to identify application-level errors. All responses are standard JSON, with a few returning binary data when needed. The Plaid API is delivered over HTTPS with TLS v1.2 or higher to ensure data privacy. HTTP and TLS versions below 1.2 are not supported. Clients must use an up-to-date root certificate bundle as the only TLS verification method; certificate pinning should not 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 can be sent either in the request body or in the headers as PLAID-CLIENT-ID and PLAID-SECRET.

Every Plaid API response includes a request_id, either in the body or, for endpoints that return binary data (such as /asset_report/pdf/get), in the response headers. For quicker support, include the request_id when contacting support about a specific API call.

API Host

https://sandbox.plaid.com (Sandbox)\nhttps://production.plaid.com (Production)\n\n

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 via the Dashboard.

API Status and Incidents

API status is available at status.plaid.com.

API status and incidents are also available programmatically via the following endpoints:

https://status.plaid.com/api/v2/status.json for current status
\n
https://status.plaid.com/api/v2/incidents.json for current and historical incidents
\n

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.

For information on institution-specific status, see 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.

API Field Format

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.

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

Postman collection

The Postman collection 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 on GitHub.

Client Libraries

See the client libraries page for more information on Plaid's client libraries.

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 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, regularly updated for breaking and non-breaking API changes. These client libraries are generated from our OpenAPI file.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Client Libraries	GitHub Repo
Node	plaid-node
Python	plaid-python
Ruby	plaid-ruby
Java	plaid-java
GO	plaid-go

Community Libraries

Explore the community-supported libraries available for Plaid listed below. If you have created your library, please contact our Support team to have it added to this list! The best way to build your library is by using the Plaid OpenAPI file.

\n
📔 Important Note
These community libraries are not officially supported by Plaid. As a result, we cannot assist with their usage, nor can we guarantee that they will be updated to accommodate the latest changes in the Plaid API.
\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Community Libraries	GitHub Repo
Elixir	by @tylerwray
Elixir	by @wfgilman
.NET	Going.Plaid, by @viceroypenguin
Node	plaid-fetch, by @heysanil. For Vercel Edge Runtime environments that don't support Axios middleware.
PHP	by @TomorrowIdeas

Link Client SDK

For information on Plaid's front-end SDKs for web and mobile, see Link.

To learn more about installing and using Link SDKs, check out the docs pages for Link on JavaScript and React (web), React Native, iOS, Android, and Hosted Link.

Note that libraries marked as (community) are not officially supported by Plaid. Plaid cannot assist 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.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Client SDK	GitHub Repo
iOS	plaid-link-ios
Android	plaid-link-android
React	react-plaid-link
React Native	react-native-plaid-link-sdk
Angular	by Mike Roberts(community)
Javascript	web
Vue	by Jeroen Claessens (community)
Flutter	by @jorgefspereira (community)

Quickstart

For a listing of Plaid sample apps, see the Resources page.

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.

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
\n
Adding new optional parameters to existing endpoints
\n
Adding new data elements to existing response schemas or webhooks
\n
Adding new enum values, including error_types and error_codes
\n
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 developer action (such as retries) 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 later, but converting an existing INTERNAL_SERVER_ERROR to a more specific error would not be.
\n
Changing the behavior for use cases or platforms are explicitly not supported.
\n
Adding new webhook_types and webhook_codes
\n
Changing the length or content of any API identifier
\n

How To Set Up your API version

The default version of the API used in any requests you make can be configured in the Dashboard 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.

Current libraries

//API Version Example\ncurl -X POST https://sandbox.plaid.com/auth/get \\\n  -H 'Content-Type: application/json' \\\n  -H 'Plaid-Version: 2020-09-14'\n\n

Legacy Libraries

//API Version Example\ncurl -X POST https://sandbox.plaid.com/auth/get \\\n  -H 'Content-Type: application/json' \\\n  -H 'Plaid-Version: 2019-05-29'\n\n

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 and /institutions/search, now require a client_id and secret for authentication instead.
\n
/item/remove 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 call will result in an error being returned instead.
\n
Several undocumented and unused fields have been removed from the institution object returned by the institutions endpoints /institutions/get, /institutions/get_by_id, and /institutions/search. The removed fields are: input_spec, credentials, include_display_data, has_mfa, mfa, and mfa_code_type.
\n
The institutions endpoints /institutions/get, /institutions/get_by_id, and /institutions/search 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.
\n
To support international payments, the response schema for the partner-only /processor/auth/get endpoint has changed. The 2018-05-22 and 2019-05-29 API releases previously extended the response schema for /auth/get in order to support international accounts, but these changes were never extended to the /processor/auth/get endpoint. This release brings the response for /processor/auth/get in line with the /auth/get 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.
\n
Previous /processor/auth/get response
\n

 \"numbers\": [{\n  \"account\": \"9900009606\",\n  \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n  \"routing\": \"011401533\",\n  \"wire_routing\": \"021000021\"\n}]\n\n

2020-09-14 API version /previous/processor/auth/get response

\"numbers\": {\n  \"ach\": [{\n    \"account\": \"9900009606\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"routing\": \"011401533\",\n    \"wire_routing\": \"021000021\"\n  }],\n  \"eft\":[{\n    \"account\": \"111122223333\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"institution\": \"021\",\n    \"branch\": \"01140\"\n  }],\n  \"international\":[{\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"bic\": \"NWBKGB21\"\n    \"iban\": \"GB29NWBK60161331926819\",\n  }],\n  \"bacs\":[{\n    \"account\": \"31926819\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"sort_code\": \"601613\"\n  }]\n}\n\n

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.
\n
Renamed the zip field to postal_code and the state field to region in all Identity and Transactions responses to be more international friendly.
\n
Identity objects in Identity responses are now embedded on the owners field of the corresponding account.
\n
Address data fields for Identity responses are now nullable and are returned with a null value when they aren’t available rather than an empty string.
\n
Added a ISO-3166-1 alpha-2 country field to all Identity and Transactions responses.
\n
The account type brokerage has been renamed to investment.
\n

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 with the new API version to see the new Schema and enable support for International institutions from the Dashboard in order to create Items for these institutions.

Auth

Before, numbers only had fields for ach (US accounts) and eft (Canadian accounts) accounts numbers:

Previous Auth Response(2018-05-22 version)

\"numbers\": {\n  \"ach\": [{\n    \"account\": \"9900009606\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"routing\": \"011401533\",\n    \"wire_routing\": \"021000021\"\n  }],\n  \"eft\":[{\n    \"account\": \"111122223333\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"institution\": \"021\",\n    \"branch\": \"01140\"\n  }]\n}\n\n

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.

New Auth response (2019-05-29 version)

\"numbers\": {\n  \"ach\": [{\n    \"account\": \"9900009606\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"routing\": \"011401533\",\n    \"wire_routing\": \"021000021\"\n  }],\n  \"eft\":[{\n    \"account\": \"111122223333\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"institution\": \"021\",\n    \"branch\": \"01140\"\n  }],\n  \"international\":[{\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"bic\": \"NWBKGB21\"\n    \"iban\": \"GB29NWBK60161331926819\",\n  }],\n  \"bacs\":[{\n    \"account\": \"31926819\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"sort_code\": \"601613\"\n  }]\n}\n\n

Identity

The previous version of Identity 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.

Previous Identity Response (2018-05-22 version)

\"identity\": {\n  \"addresses\": [{\n    \"accounts\": [\n      \"Plaid Checking 0000\",\n      \"Plaid Saving 1111\",\n      \"Plaid CD 2222\"\n    ],\n    \"data\": {\n      \"city\": \"Malakoff\",\n      \"state\": \"NY\",\n      \"street\": \"2992 Cameron Road\",\n      \"zip\": \"14236\"\n    },\n    \"primary\": true\n  }],\n  ...\n}\n\n

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.

New Identity Response (2019-05-29 version)

\"accounts\": [{\n  ...\n  \"owners\": [{\n    \"addresses\": [{\n      \"data\": {\n        \"city\": \"Malakoff\",\n        \"region\": \"NY\",\n        \"street\": \"2992 Cameron Road\",\n        \"postal_code\": \"14236\",\n        \"country\": \"US\",\n      },\n      \"primary\": true\n    }]\n  }],\n  ...\n}]\n\n

Transaction

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 were also made to Transactions.

Previous Transaction Response (2018-05-22 version)

\"transactions\": [{\n  ...\n  \"location\": {\n    \"address\": \"300 Post St\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"zip\": \"94108\",\n    \"lat\": null,\n    \"lon\": null\n  },\n  ...\n]\n\n

New Transaction Response (2019-05-29 version)

\"transactions\": [{\n  ...\n  \"location\": {\n    \"address\": \"300 Post St\",\n    \"city\": \"San Francisco\",\n    \"region\": \"CA\",\n    \"postal_code\": \"94108\",\n    \"country\": \"US\",\n    \"lat\": null,\n    \"lon\": null\n  },\n  ...\n]}\n\n

Institution

Changes to the institutions schema effects responses from all of the institutions API endpoints:

The previous version of the Institution schema did not include the country of the institution as part of the response.

Previous Institution Response (2018-05-22 version)

\"institution\": {\n  \"credentials\": [{\n    \"label\": \"User ID\",\n    \"name\": \"username\",\n    \"type\": \"text\"\n    }, {\n    \"label\": \"Password\",\n    \"name\": \"password\",\n    \"type\": \"password\"\n  }],\n  \"has_mfa\": true,\n  \"institution_id\": \"ins_109512\",\n  \"mfa\": [\n    \"code\",\n    \"list\",\n    \"questions\",\n    \"selections\"\n  ],\n  \"name\": \"Houndstooth Bank\",\n  \"products\": [\n    \"auth\",\n    \"balance\",\n    \"identity\",\n    \"transactions\"\n  ],\n  // included when options.include_status is true\n  \"status\": {object}\n}\n\n

New Institution response(2019-05-29 version)

\"institution\": {\n  \"country_codes\": [\"US\"],\n  \"credentials\": [{\n    \"label\": \"User ID\",\n    \"name\": \"username\",\n    \"type\": \"text\"\n    }, {\n    \"label\": \"Password\",\n    \"name\": \"password\",\n    \"type\": \"password\"\n  }],\n  \"has_mfa\": true,\n  \"institution_id\": \"ins_109512\",\n  \"mfa\": [\n    \"code\",\n    \"list\",\n    \"questions\",\n    \"selections\"\n  ],\n  \"name\": \"Houndstooth Bank\",\n  \"products\": [\n    \"auth\",\n    \"balance\",\n    \"identity\",\n    \"transactions\"\n  ],\n  // included when options.include_status is true\n  \"status\": {object}\n}\n\n

Version 2018-05-22

The Auth numbers schema has changed to support ACH (US-based) and EFT (Canadian-based) account numbers
\n
Added the iso_currency_code and unofficial_currency_code fields to all Accounts and Transactions responses
\n

Enable support for Canadian institutions from the Dashboard and then test in the Sandbox 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:

Previous Auth response (2017-03-08 version)

\"numbers\": [{\n  \"account\": \"9900009606\",\n  \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n  \"routing\": \"011401533\",\n  \"wire_routing\": \"021000021\"\n}]\n\n

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.

New Auth response (2018-05-22 version) for ACH numbers

\"numbers\": {\n   \"ach\": [{\n    \"account\": \"9900009606\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"routing\": \"011401533\",\n    \"wire_routing\": \"021000021\"\n   }],\n   \"eft\": []\n}\n\n

New Auth response (2018-05-22 version) for EFT Numbers

\"numbers\": {\n   \"ach\":[],\n   \"eft\":[{\n    \"account\": \"111122223333\",\n    \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\",\n    \"institution\": \"021\",\n    \"branch\": \"01140\"\n   }]\n}\n\n

Version 2017-03-08

The 2017-03-08 version was the first versioned release of the API.

Plaid Postman Collection

Learn more about the Plaid Postman Collection, which allows you to send API requests without code

Introduction

Plaid offers a Postman Collection 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, and (optionally) the Postman desktop application. Once you have all the prerequisites, visit our GitHub page and click the \"Run in Postman\" button to load up the Plaid collection of endpoints.

\n\n

Webhooks

API reference for webhooks

📹 Prefer to learn by watching? Our video tutorial walks you through the basics of incorporating Plaid webhooks into your application.

⚠️ Looking for webhook schemas? The reference documentation for specific webhooks (Transactions, Auth, Assets, Identity, Identity Verification, Monitor, Investments, Liabilities, Payment Initiation, Income, Virtual Accounts, Items, and Transfer) has moved to its respective API reference pages.

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

Configuring Webhooks

Webhooks are typically configured via the webhook parameter of /link/token/create, 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 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.

Plaid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses:

52.21.26.131
\n
52.21.47.157
\n
52.41.247.19
\n
52.88.82.239
\n

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.

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 Application using Webhooks

You should design your application to handle duplicate and out-of-order webhooks. Ensure idempotency 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, 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, /sandbox/income/fire_webhook, or /sandbox/transfer/fire_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 or Request Bin 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 and handleItemWebhook.js These files contain webhook handling code for the Node-based Plaid Pattern sample app.

Base URL

https://sandbox.plaid.com/\n\n

","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Libraries","slug":"libraries"},{"content":"API versioning and changelog","slug":"api-versioning-and-changelog"},{"content":"Plaid Postman Collection","slug":"plaid-postman-collection"},{"content":"Webhooks","slug":"webhooks"},{"content":"Base URL","slug":"base-url"}],"owner":"32923208","collectionId":"841d643c-b27c-413c-8a04-e3375741c317","publishedId":"2sAYBUDsTy","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-11-24T22:37:24.000Z"},"item":[{"name":"API Reference","item":[],"id":"154f48d8-fe80-4aad-867d-066077a0e7ae","description":"

A comprehensive reference for integrating with Plaid API endpoints

\n","_postman_id":"154f48d8-fe80-4aad-867d-066077a0e7ae"},{"name":"Verify Webhooks","item":[],"id":"98dd3da7-04ec-4f39-b627-b87a203620b3","description":"

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

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

\n","_postman_id":"98dd3da7-04ec-4f39-b627-b87a203620b3"},{"name":"Payments & Funding","item":[{"name":"Auth","item":[{"name":"Authentication","id":"8ec7215e-e17a-4e43-b1fd-12e7cf1cb3ca","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":" {\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"access_token\": {{access_token}}\n\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/auth/get","description":"

Authentication Get

This endpoint is used to retrieve the bank account and bank identification numbers associated with an Item's checking and savings accounts, along with high-level account data and balances when available.

Request Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data type	Description	Choice
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.	optional
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.	optional
access_token	string	The access token associated with the Item data is being requested for.	required
options	object	An optional object to filter /auth/get results.	optional
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.	optional

Response Defintion

Key	Type	Description
`account_id`	string	Unique identifier for the account, case-sensitive. Changes if access token changes or account details are updated.
`balances`	object	Contains fields describing the account's balance. Includes `available`, `current`, `limit`, etc.
├─ `available`	nullable number	Funds available for withdrawal.
├─ `current`	nullable number	Total funds in/owed by the account.
├─ `limit`	nullable number	Credit or overdraft limit (if applicable).
├─ `iso_currency_code`	nullable string	ISO-4217 currency code of the balance.
├─ `unofficial_currency_code`	nullable string	Non-ISO currency code (e.g., cryptocurrencies).
├─ `last_updated_datetime`	nullable string	Timestamp indicating the oldest acceptable balance.
`mask`	nullable string	Last 2-4 characters of the account's number. May not match what the bank displays.
`name`	string	Name of the account (user-defined or institution-defined).
`official_name`	nullable string	Official name provided by the institution.
`type`	string	Account type (e.g., `investment`, `credit`, `depository`, `loan`, `other`).
`subtype`	nullable string	Account subtype (e.g., `checking`, `savings`, `crypto exchange`).
`verification_status`	string	Status of account verification (e.g., `automatically_verified`, `pending_manual_verification`).
`verification_insights`	object	Insights from database verification (if applicable).
`network_status`	object	Status of account and routing numbers within Plaid’s network.
├─ `has_numbers_match`	boolean	Indicates if matching accounts exist.
├─ `is_numbers_match_verified`	boolean	Indicates if matching accounts are verified.
`numbers`	object	Identifying numbers for electronic transfers. Includes `ACH`, `EFT`, `IBAN`, or `BACS` fields.
├─ `ach`	array	ACH account numbers and routing details.
├─ `eft`	array	EFT account numbers and branch details.
├─ `international`	array	IBAN numbers and BIC details for international accounts.
├─ `bacs`	array	BACS account numbers and sort codes (UK-specific).
`item`	object	Metadata about the Item (e.g., ID, institution, webhook URL).
├─ `item_id`	string	Unique ID for the Item.
├─ `institution_id`	nullable string	ID of the institution associated with the Item.
├─ `webhook`	nullable string	Webhook URL for receiving Item updates.
├─ `error`	nullable object	Contains error details if an error occurred.

Bank Transfer Event List

This endpoint allows you to retrieve a list of bank transfer events.

Request Body

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
client_id (required)	string	The client ID for Plaid.
secret (required)	string	The secret key for Plaid.
start_date (optional)	string	The start date for the bank transfer events.
end_date (optional)	string	The end date for the bank transfer events.
bank_transfer_id (optional)	string	The ID of the bank transfer.
account_id (optional)	string	The ID of the account.
bank_transfer_type (optional)	string	The type of bank transfer.
event_types (optional)	array of strings	An array of event types to filter the results.
count (optional)	integer	The number of results to return.
offset (optional)	integer	The offset for pagination.
origination_account_id (optional)	string	The ID of the origination account.
direction (optional)	string	The direction of the bank transfer.

Response Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
bank_transfer_events	object
/event_id	integer	Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: 0
/timestamp	string	The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z. Format: date-time
/event_type	string	The type of event that this bank transfer represents. Possible values: `pending`, `cancelled`, `failed`, `posted`, `reversed`.
/account_id	string	The account ID associated with the bank transfer.
/bank_transfer_id	string	Plaid’s unique identifier for a bank transfer.
/origination_account_id	nullable string	The ID of the origination account that this balance belongs to.
/bank_transfer_type	string	The type of bank transfer. Possible values: `debit`, `credit`.
/bank_transfer_amount	string	The bank transfer amount.
/bank_transfer_iso_currency_code	string	The currency of the bank transfer amount.
/failure_reason	nullable object	The failure reason if the type of this transfer is \"failed\" or \"reversed\". Null value otherwise.
/ach_return_code	nullable string	The ACH return code, e.g. R01. A return code is provided if the transfer status is reversed.
/description	string	A human-readable description of the reason for the failure or reversal.
/direction	nullable string	Indicates the direction of the transfer. Possible values: `outbound`, `inbound`, `null`.
request_id	string	A unique identifier for the request, used for troubleshooting. This identifier is case-sensitive.

","urlObject":{"path":["bank_transfer","event","list"],"host":["https://sandbox.plaid.com"],"query":[],"variable":[]}},"response":[{"id":"8218f2a6-226b-4f9b-b026-b666b1cc5d79","name":"Bank Transfer Event","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": \"${PLAID_CLIENT_ID}\",\n \"secret\": \"${PLAID_SECRET}\",\n \"start_date\": String,\n \"end_date\": String,\n \"bank_transfer_id\": String,\n \"account_id\": String,\n \"bank_transfer_type\": String,\n \"event_types\": [String],\n \"count\": Number,\n \"offset\": Number,\n \"origination_account_id\": String,\n \"direction\": String\n }","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/bank_transfer/event/list"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"bank_transfer_events\": [\n {\n \"account_id\": \"6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B\",\n \"bank_transfer_amount\": \"12.34\",\n \"bank_transfer_id\": \"460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9\",\n \"bank_transfer_iso_currency_code\": \"USD\",\n \"bank_transfer_type\": \"credit\",\n \"direction\": \"outbound\",\n \"event_id\": 1,\n \"event_type\": \"pending\",\n \"failure_reason\": null,\n \"origination_account_id\": \"\",\n \"timestamp\": \"2020-08-06T17:27:15Z\"\n }\n ],\n \"request_id\": \"mdqfuVxeoza6mhu\"\n}"}],"_postman_id":"c7853457-c0b1-42de-9ba3-084d00761317"},{"name":"Bank Transfer Event Sync","id":"92551964-d8ba-4b0d-96ec-f4c4c66784cc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"after_id\": 0,\n \"count\": 25\n }","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/bank_transfer/event/sync","description":"

This API endpoint is used to sync bank transfer events.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Required	Description	Constraints
`client_id`	string	Yes	Your Plaid API `client_id`. This must be provided either in the `PLAID-CLIENT-ID` header or as part of the request body.	N/A
`secret`	string	Yes	Your Plaid API `secret`. This must be provided either in the `PLAID-SECRET` header or as part of the request body.	N/A
`after_id`	integer	Yes	The latest (largest) `event_id` fetched via the sync endpoint, or `0` initially.	Minimum: `0`
`count`	integer	No	The maximum number of bank transfer events to return.	Default: `25`, Minimum: `1`, Maximum: `25`

Response Definition

Key	Data Type	Required	Description	Constraints
`event_id`	integer	Yes	Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.	Minimum: `0`
`timestamp`	string	Yes	The datetime when this event occurred, in the format `2006-01-02T15:04:05Z`.	Format: date-time
`event_type`	string	Yes	The type of event that this bank transfer represents.	Possible values: `pending`, `cancelled`, `failed`, `posted`, `reversed`
`account_id`	string	Yes	The account ID associated with the bank transfer.	N/A
`bank_transfer_id`	string	Yes	Plaid’s unique identifier for the bank transfer.	N/A
`origination_account_id`	string	No	The ID of the origination account for the balance, can be `null`.	Nullable
`bank_transfer_type`	string	Yes	The type of bank transfer: either debit or credit. A debit indicates money into the origination account, a credit indicates money out of it.	Possible values: `debit`, `credit`
`bank_transfer_amount`	string	Yes	The amount of the bank transfer.	N/A
`bank_transfer_iso_currency_code`	string	Yes	The currency of the bank transfer amount.	N/A
`failure_reason`	object	No	The failure reason if the transfer type is `failed` or `reversed`, `null` otherwise.	Nullable
`ach_return_code`	string	No	The ACH return code (e.g., `R01`) if the transfer status is reversed.	Nullable
`description`	string	No	A human-readable description of the reason for the failure or reversal.	N/A
`direction`	string	No	Indicates the direction of the transfer: `outbound` for API-initiated transfers, `inbound` for payments received.	Possible values: `outbound`, `inbound`, `null`
`request_id`	string	Yes	A unique identifier for the request, useful for troubleshooting.	Case sensitive

API reference for Auth endpoints and webhooks

These endpoints 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.

Endpoints Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoints	Description
`/auth/get`	Fetch account information
`/bank_transfer/event/list`	Search for updates on micro-deposit verification statuses based on filter criteria
`/bank_transfer/event/sync`	Get updates on micro-deposit verification statuses using a cursor

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

See also	Description
`/processor/token/create`	Create a token for using Auth with a processing partner
`/sandbox/processor_token/create`	Create a token for testing Auth with a processing partner
`/processor/stripe/bank_account_token/create`	Create a token for using Auth with Stripe as a processing partner
`/sandbox/item/set_verification_status`	Change a Sandbox Item's micro-deposit verification status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Webhooks	Description
`DEFAULT_UPDATE`	Item has account(s) with updated Auth data
`AUTOMATICALLY_VERIFIED`	Item has been verified
`VERIFICATION_EXPIRED`	Item verification has failed
`BANK_TRANSFERS_EVENTS_UPDATE`	New micro-deposit verification events available
`SMS_MICRODEPOSITS_VERIFICATION`	Text message verification status has changed

","_postman_id":"ea20b095-9ce8-4996-95d1-65a33d2dd5f3","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}},{"name":"Balance","item":[{"name":"Balance Data","id":"2a9b0925-00a8-416c-b463-94abfeccde44","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":" {\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"access_token\": {{access_token}},\n \"options\":{\n \"account_ids\":[\"qnVWlalKkNIGNQJWg7wXHN3aXyZammFgrMMeE\"]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/accounts/balance/get","description":"

This endpoint endpoint returns the real-time balance for each of an Item's accounts.

Request Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Required	Description	Constraints
`access_token`	string	Yes	The access token associated with the Item for which data is being requested.	N/A
`secret`	string	Yes	Your Plaid API secret. The secret can be provided either in the `PLAID-SECRET` header or as part of a request body.	N/A
`client_id`	string	Yes	Your Plaid API client_id. The client_id can be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.	N/A
`options`	object	No	Optional parameters for `/accounts/balance/get`.	N/A
`account_ids`	[string]	No	A list of `account_ids` to retrieve for the Item. Default value is `null`. Note: An error will be returned if a provided `account_id` is not associated with the Item.	N/A
`min_last_updated_datetime`	string	No	Timestamp in ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when requesting `/accounts/balance/get`. Required for non-depository accounts at `ins_128026` (Capital One).	Format: date-time
			For all other institutions and depository accounts at Capital One, this field is ignored. If no acceptable balance is available, an `INVALID_RESULT` error with the code `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned.

Response Defintion

The response will be a JSON object with the following schema:

Key	Description
`accounts`	An array of financial institution accounts associated with the Item. If `/accounts/balance/get` was called, each account will include real-time balance information.
`account_id`	Plaid’s unique identifier for the account. It may change if Plaid can't reconcile the account with the data from the financial institution or if the access_token is deleted and recreated. It is case-sensitive.
`balances`	A set of fields describing the balance for an account. Balance information may be cached unless the value was returned by `/accounts/balance/get`.
`available`	The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, it equals the limit minus the current balance and pending transactions.
`current`	The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed, while a negative balance indicates the lender owing the account holder.
`limit`	The credit limit for credit-type accounts or the pre-arranged overdraft limit for depository-type accounts.
`iso_currency_code`	The ISO-4217 currency code of the balance.
`unofficial_currency_code`	The unofficial currency code associated with the balance.
`last_updated_datetime`	Timestamp indicating the oldest acceptable balance when making a request to `/accounts/balance/get`.
`mask`	The last 2-4 alphanumeric characters of an account's official account number.
`name`	The name of the account, either assigned by the user or by the financial institution itself.
`official_name`	The official name of the account as given by the financial institution.
`type`	Type of the account, such as `investment`, `credit`, `depository`, `loan`, or `other`.
`subtype`	Specific subtype of the account, such as `401k`, `checking`, `credit card`, `savings`, etc.
`verification_status`	The current verification status of an Auth Item initiated through micro-deposits or database verification.
`verification_insights`	Insights from performing database verification for the account.
`network_status`	Status information about the account and routing number in the Plaid network.
`has_numbers_match`	Indicates whether Plaid found a matching account for the ACH account and routing number.
`is_numbers_match_verified`	Indicates if at least one matching account for the ACH account and routing number is already verified.
`previous_returns`	Information about known ACH returns for the account and routing number.
`has_previous_administrative_return`	Indicates whether Plaid's data sources include a known administrative ACH return for account and routing number.
`account_number_format`	Indicates whether the account number format is valid, invalid, or unknown for the institution.
`persistent_account_id`	A unique identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts.
`holder_category`	Categorization of the account as either personal or business.
`item`	Metadata about the Item, including `item_id`, `institution_id`, and `webhook`.
`error`	Errors categorized by `error_type` and `error_code`.
`error_type`	Broad categorization of the error (e.g., `INVALID_REQUEST`, `INSTITUTION_ERROR`, `API_ERROR`, etc.).
`error_code`	Specific error code associated with the error.
`error_message`	Developer-friendly representation of the error code.
`display_message`	User-friendly message associated with the error.
`request_id`	A unique ID identifying the request, useful for troubleshooting.

API reference for Balance endpoints and webhooks

Endpoint Overiew

\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoints	Description
`/accounts/balance/get`	Fetch real-time account balances

","_postman_id":"ce955af8-0da7-4e49-bca0-da8d51139ca2","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}},{"name":"Identity","item":[{"name":"Retrieve identity data","id":"984c740d-e738-4dfe-b3d1-2789b5ad3a17","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"access_token\": {{access_token}}\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/identity/get","description":"

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

Request Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data type	Description
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	string	The access token associated with the Item data is being requested for.
options	object	An optional object to filter /identity/get results.
account_ids	array of 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.

Response Data Defintion

Key	Data Type	Description
accounts	object	The accounts for which Identity data has been requested.
account_id	string	Plaid’s unique identifier for the account. It changes if the account cannot be reconciled with the data or if the access token is deleted and reissued. Closed accounts are not returned. Case-sensitive.
balances	object	A set of fields describing the balance for an account. Balance information may be cached unless retrieved via `/accounts/balance/get`.
available	nullable	The funds available for withdrawal. May be cached unless retrieved by `/accounts/balance/get`. Format: double.
current	nullable	The total amount in or owed by the account. Cached unless retrieved via `/accounts/balance/get`. Format: double.
limit	nullable	Credit or overdraft limit, depending on account type. Format: double.
iso_currency_code	nullable	ISO-4217 currency code. Null if `unofficial_currency_code` is present.
unofficial_currency_code	nullable	Currency code for non-ISO currencies like cryptocurrencies.
last_updated_datetime	nullable	Timestamp in ISO 8601 format for the oldest acceptable balance. Used for non-depository accounts at specific institutions like Capital One. Format: date-time.
mask	nullable	Last 2-4 alphanumeric characters of the account's official number. May not be unique or match the mask shown by the bank.
name	string	The name of the account, as assigned by the user or institution.
official_name	nullable	The official name of the account as provided by the financial institution.
type	string	The type of account (e.g., investment, credit, depository, loan, other).
subtype	nullable	Subtypes like checking, savings, crypto exchange, etc.
verification_status	string	Verification status of the account (e.g., `automatically_verified`, `pending_manual_verification`). Applies to Auth Items only.
verification_insights	object	Insights from database verification (returned for Auth Items created via Database Insights).
network_status	object	Status information about the account and routing number in the Plaid network.
has_numbers_match	boolean	Indicates if a matching account was found for the ACH account and routing number.
is_numbers_match_verified	boolean	Indicates if a matching account for the ACH account and routing number is already verified.
previous_returns	object	Information about known ACH returns for the account and routing number.
persistent_account_id	string	Unique identifier for accounts across multiple Items for depository accounts. Used at institutions like Chase and PNC.
holder_category	nullable	Indicates if the account is personal or business (`personal`, `business`, `unrecognized`).
owners	[object]	Data about account owners, including names, phone numbers, emails, and addresses.
names	[string]	List of names associated with the account by the institution.
phone_numbers	[object]	Phone numbers linked to the account. Includes type (`home`, `mobile`, `other`) and if primary.
emails	[object]	Email addresses linked to the account. Includes type (`primary`, `secondary`, `other`) and if primary.
addresses	[object]	Address details linked to the account, including city, region, street, postal code, and country. Identifies if primary.
account_number_format	string	Indicates the validity of the account number format (`valid`, `invalid`, `unknown`).

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}},"urlObject":{"path":["identity","get"],"host":["https://sandbox.plaid.com"],"query":[],"variable":[]}},"response":[{"id":"9f2154c9-5198-4f30-a8f8-85f73f2d4313","name":"Retrieve identity data","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": \"${PLAID_CLIENT_ID}\",\n \"secret\": \"${PLAID_SECRET}\",\n \"access_token\": String\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/identity/get"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"accounts\": [\n {\n \"account_id\": \"BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp\",\n \"balances\": {\n \"available\": 100,\n \"current\": 110,\n \"iso_currency_code\": \"USD\",\n \"limit\": null,\n \"unofficial_currency_code\": null\n },\n \"mask\": \"0000\",\n \"name\": \"Plaid Checking\",\n \"official_name\": \"Plaid Gold Standard 0% Interest Checking\",\n \"owners\": [\n {\n \"addresses\": [\n {\n \"data\": {\n \"city\": \"Malakoff\",\n \"country\": \"US\",\n \"postal_code\": \"14236\",\n \"region\": \"NY\",\n \"street\": \"2992 Cameron Road\"\n },\n \"primary\": true\n },\n {\n \"data\": {\n \"city\": \"San Matias\",\n \"country\": \"US\",\n \"postal_code\": \"93405-2255\",\n \"region\": \"CA\",\n \"street\": \"2493 Leisure Lane\"\n },\n \"primary\": false\n }\n ],\n \"emails\": [\n {\n \"data\": \"accountholder0@example.com\",\n \"primary\": true,\n \"type\": \"primary\"\n },\n {\n \"data\": \"accountholder1@example.com\",\n \"primary\": false,\n \"type\": \"secondary\"\n },\n {\n \"data\": \"extraordinarily.long.email.username.123456@reallylonghostname.com\",\n \"primary\": false,\n \"type\": \"other\"\n }\n ],\n \"names\": [\n \"Alberta Bobbeth Charleson\"\n ],\n \"phone_numbers\": [\n {\n \"data\": \"1112223333\",\n \"primary\": false,\n \"type\": \"home\"\n },\n {\n \"data\": \"1112224444\",\n \"primary\": false,\n \"type\": \"work\"\n },\n {\n \"data\": \"1112225555\",\n \"primary\": false,\n \"type\": \"mobile\"\n }\n ]\n }\n ],\n \"subtype\": \"checking\",\n \"type\": \"depository\"\n },\n {\n \"account_id\": \"3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr\",\n \"balances\": {\n \"available\": 200,\n \"current\": 210,\n \"iso_currency_code\": \"USD\",\n \"limit\": null,\n \"unofficial_currency_code\": null\n },\n \"mask\": \"1111\",\n \"name\": \"Plaid Saving\",\n \"official_name\": \"Plaid Silver Standard 0.1% Interest Saving\",\n \"owners\": [\n {\n \"addresses\": [\n {\n \"data\": {\n \"city\": \"Malakoff\",\n \"country\": \"US\",\n \"postal_code\": \"14236\",\n \"region\": \"NY\",\n \"street\": \"2992 Cameron Road\"\n },\n \"primary\": true\n },\n {\n \"data\": {\n \"city\": \"San Matias\",\n \"country\": \"US\",\n \"postal_code\": \"93405-2255\",\n \"region\": \"CA\",\n \"street\": \"2493 Leisure Lane\"\n },\n \"primary\": false\n }\n ],\n \"emails\": [\n {\n \"data\": \"accountholder0@example.com\",\n \"primary\": true,\n \"type\": \"primary\"\n },\n {\n \"data\": \"accountholder1@example.com\",\n \"primary\": false,\n \"type\": \"secondary\"\n },\n {\n \"data\": \"extraordinarily.long.email.username.123456@reallylonghostname.com\",\n \"primary\": false,\n \"type\": \"other\"\n }\n ],\n \"names\": [\n \"Alberta Bobbeth Charleson\"\n ],\n \"phone_numbers\": [\n {\n \"data\": \"1112223333\",\n \"primary\": false,\n \"type\": \"home\"\n },\n {\n \"data\": \"1112224444\",\n \"primary\": false,\n \"type\": \"work\"\n },\n {\n \"data\": \"1112225555\",\n \"primary\": false,\n \"type\": \"mobile\"\n }\n ]\n }\n ],\n \"subtype\": \"savings\",\n \"type\": \"depository\"\n }\n ],\n \"item\": {\n \"available_products\": [\n \"balance\",\n \"investments\"\n ],\n \"billed_products\": [\n \"assets\",\n \"auth\",\n \"identity\",\n \"liabilities\",\n \"transactions\"\n ],\n \"consent_expiration_time\": null,\n \"error\": null,\n \"institution_id\": \"ins_3\",\n \"item_id\": \"eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6\",\n \"update_type\": \"background\",\n \"webhook\": \"https://www.genericwebhookurl.com/webhook\"\n },\n \"request_id\": \"3nARps6TOYtbACO\"\n}"}],"_postman_id":"984c740d-e738-4dfe-b3d1-2789b5ad3a17"},{"name":"Retrieve identity match score","id":"2c592c39-86c7-49e9-a087-f404cc4b9b0e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"access_token\": {{access_token}},\n \"user\": {\n \"phone_number\": String,\n \"legal_name\": String,\n \"email_address\": String,\n \"address\": {\n \"street\": String,\n \"region\": String,\n \"country\": String,\n \"city\": String,\n \"postal_code\": String\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/identity/match ","description":"

Identity Match

The endpoint allows you to 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.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
`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 being requested.
`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.
`legal_name`	`string`	The user's full legal name.
`phone_number`	`string`	The user's phone number in E.164 format: `+{countrycode}{number}` (e.g., `+14157452130`). Phone numbers in other formats will be parsed on a best-effort basis. Invalid or non-realistic numbers may cause the request to fail, even in the Sandbox environment.
`email_address`	`string`	The user's email address.
`address`	`object`	Data about the components comprising an address.
`city`	`string`	The full city name.
`region`	`string`	The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `\"NC\"`.
`street`	`string`	The full street address. Example: `\"564 Main Street, APT 15\"`.
`postal_code`	`string`	The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`.
`country`	`string`	The ISO 3166-1 alpha-2 country code.
`options`	`object`	An optional object to filter `/identity/match` results.
`account_ids`	`[string]`	An array of `account_ids` to perform fuzzy match.

Response Data Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
id	string	The unique identifier of the sweep.
funding_account_id	string	The ID of the funding account used, available in the Plaid Dashboard, to determine which business checking account is credited or debited.
ledger_id	string?	Plaid’s unique identifier for a Plaid Ledger Balance (nullable).
created	string	The datetime when the sweep occurred, in RFC 3339 format.
amount	string	Signed decimal amount of the sweep (e.g., \"-10.00\"). If not present, the sweep was net-settled to zero.
iso_currency_code	string	The currency of the sweep (e.g., \"USD\").
settled	string?	The date when the sweep settled, in YYYY-MM-DD format (nullable).
status	string?	The status of the sweep transfer. Possible values: `pending`, `posted`, `settled`, `returned`, `failed`, `null`.
trigger	string?	The trigger of the sweep. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate`.
description	string	The description of the deposit that will be passed to the receiving bank (up to 10 characters).
network_trace_id	string?	The trace identifier for the transfer based on its network (nullable). Will be set after the transfer has posted.
request_id	string	A unique identifier for the request used for troubleshooting. This is case-sensitive.

Uploads Get Identity Documents

This endpoint allows the user to retrieve identity details when using Identity Document Upload.

Request Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Descripion
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	string	The access token associated with the Item data is being requested for

Response Data Defintion

Key	Description
account_id	Plaid’s unique identifier for the account. Changes if the account is reconciled or if credentials are updated.
balances	A set of fields describing the balance for an account. May be cached unless fetched via `/accounts/balance/get`.
available	The amount available to be withdrawn, or for credit-type accounts, the limit less current balance and pending flows.
current	The total amount of funds in or owed by the account. For credit accounts, it indicates the amount owed.
limit	For credit accounts, it represents the credit limit; for depository accounts, it may represent the overdraft limit.
iso_currency_code	The ISO-4217 currency code of the balance. Null if unofficial currency is used.
unofficial_currency_code	The unofficial currency code associated with the balance (e.g., cryptocurrencies).
last_updated_datetime	Timestamp of the oldest acceptable balance when making a request. Used for Capital One verification.
mask	The last 2-4 characters of the account’s official account number.
name	The name of the account, either assigned by the user or by the financial institution.
official_name	The official name of the account as given by the financial institution.
type	Type of the account (e.g., investment, credit, depository, loan, other).
subtype	Specific subtype of the account (e.g., 401k, checking, savings, mortgage, etc.).
verification_status	The current verification status of an Auth Item initiated through micro-deposits or database verification.
verification_insights	Insights from database verification for the account. Only for Auth Items created via Database Insights.
network_status	Status information about the account and routing number in the Plaid network.
has_numbers_match	Indicates if a matching account was found for the ACH account and routing number.
is_numbers_match_verified	Indicates if the matching account for the ACH account is already verified.
previous_returns	Information about known ACH returns for the account and routing number.
has_previous_administrative_return	Indicates if there was an administrative ACH return for the account and routing number.
account_number_format	Indicates whether the account number format is valid for the institution (valid, invalid, unknown).
persistent_account_id	A unique identifier for accounts at institutions with Tokenized Account Numbers.
holder_category	Categorization of the account as either personal or business (currently in beta).
owners	Data about the account owner(s), including name(s), phone numbers, and addresses.
names	A list of names associated with the account by the financial institution.
phone_numbers	A list of phone numbers associated with the account.
data	The phone number.
primary	Indicates if the phone number is the primary contact number.
type	Type of phone number (home, work, mobile, etc.).
emails	A list of email addresses associated with the account.
data	The email address.
primary	Indicates if the email address is the primary contact email.
type	Type of email account (primary, secondary, etc.).
addresses	Data about the various addresses associated with the account.
data	Data about the components comprising an address.
city	The city name of the address.
region	The region or state of the address.
street	The street address (e.g., 564 Main Street, APT 15).
postal_code	The postal/ZIP code of the address.
country	The ISO 3166-1 alpha-2 country code of the address.
primary	Indicates if the address is the primary address on the account.
documents	Data about documents uploaded as proof of account ownership.

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.

Endpoints Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoints	Description
`/identity/get`	Fetch identity data
`/identity/match`	Match client identity with bank identity
`/identity/documents/uploads/get`	Get Identity data parsed from an uploaded bank statement

","_postman_id":"58d847c7-d1b0-4621-a1ab-34790b2f23b9","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}},{"name":"Signal Endpoints","item":[{"name":"Evaluate ACH Transaction","id":"f8dd2694-7c4e-4eb7-b5ca-28e62ee3d7f4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"access_token\": {{access_token}},\n \"account_id\": {{account_id}},\n \"client_transaction_id\": \"txn12345\",\n \"amount\": 123.45\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/signal/evaluate","description":"

Evaluate ACH Transaction

This endpoint allows you to evaluate to evaluate a planned ACH transaction to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.

Request Body Defintion

Parameter	Data Type	Required	Description
`client_id`	string	Yes	Your Plaid API `client_id`. Can be provided in the `PLAID-CLIENT-ID` header or as part of the request body.
`secret`	string	Yes	Your Plaid API `secret`. Can be provided in the `PLAID-SECRET` header or as part of the request body.
`access_token`	string	Yes	The access token associated with the Item data being requested.
`account_id`	string	Yes	The `account_id` of the funding source for the proposed transaction. This ID is returned by the `/accounts/get` endpoint. Will return an `INVALID_ACCOUNT_ID` error if invalid.
`client_transaction_id`	string	Yes	Unique ID for the transaction. Can map to your internal identifier. Must be 1–36 characters long.
`amount`	number	Yes	The transaction amount in USD (e.g., `102.05`).
`user_present`	boolean	No	`true` if the end user is present during the ACH transfer; `false` otherwise.
`client_user_id`	string	No	Unique ID identifying the end user in your system. Avoid using personally identifiable information like email or phone number.
`is_recurring`	boolean	No	`true` if the transaction is recurring; `false` otherwise.
`default_payment_method`	string	No	Default payment method for the transaction. Possible values: `SAME_DAY_ACH`, `NEXT_DAY_ACH`, `STANDARD_ACH`, `REAL_TIME_PAYMENTS`, `DEBIT_CARD`, `MULTIPLE_PAYMENT_METHODS`.
`user`	object	No	Details about the end user initiating the transaction.
`name.prefix`	string	No	The user's name prefix (e.g., \"Mr.\").
`name.given_name`	string	No	The user's given name. If the user has a one-word name, use this field.
`name.middle_name`	string	No	The user's middle name.
`name.family_name`	string	No	The user's family name or surname.
`name.suffix`	string	No	The user's name suffix (e.g., \"II\").
`phone_number`	string	No	The user's phone number in E.164 format (e.g., `+14151234567`).
`email_address`	string	No	The user's email address.
`address.city`	string	No	The full city name.
`address.region`	string	No	The region or state (e.g., \"NC\").
`address.street`	string	No	The full street address (e.g., \"564 Main Street, APT 15\").
`address.postal_code`	string	No	The postal code.
`address.country`	string	No	The ISO 3166-1 alpha-2 country code.
`device.ip_address`	string	No	The IP address of the device initiating the transaction.
`device.user_agent`	string	No	The user agent of the device initiating the transaction (e.g., \"Mozilla/5.0\").
`ruleset_key`	string	No	The key of the Ruleset to use for the transaction. This feature is in closed beta. Contact Plaid to request access.

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
`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.
`customer_initiated_return_risk`	object	Contains a risk score and tier for evaluating the transaction return risk of an unauthorized debit. Common return codes include \"R05\", \"R07\", \"R10\", \"R11\", \"R29\". These returns typically have a return time frame of up to 60 calendar days.
`score`	integer	A score from 1-99 indicating the transaction return risk (higher score suggests higher risk). Minimum: 1, Maximum: 99.
`risk_tier`	integer	Risk tiers (1-5) indicating the projected likelihood of a return: - 1: 0.00% - 0.02% - 2: 0.02% - 0.05% - 3: 0.05% - 0.1% - 4: 0.1% - 0.5% - 5: >0.5%
`bank_initiated_return_risk`	object	Contains a risk score and tier for evaluating return risk due to overdraft or ineligible accounts. Common return codes include \"R01\", \"R02\", \"R03\", \"R04\", \"R06\", \"R08\", \"R09\", \"R13\", \"R16\", \"R17\", \"R20\", \"R23\".
`score`	integer	A score from 1-99 indicating the transaction return risk (higher score suggests higher risk). Minimum: 1, Maximum: 99.
`risk_tier`	integer	Risk tiers (1-8) indicating projected likelihood of a return: - 1: 0.0% - 0.5% - 2: 0.5% - 1.5% - 3: 1.5% - 3% - 4: 3% - 5% - 5: 5% - 10% - 6: 10% - 15% - 7: 15% - 50% - 8: >50%
`core_attributes`	object	Additional data for assessing ACH return risk, e.g., days since first Plaid connection, count of Plaid connections in the past 7/30 days, whether the funding account is a savings/money market account.
`ruleset`	nullable object	Details about the transaction result evaluated by the requested Ruleset. If a `ruleset_key` is not provided, this field is omitted.
`ruleset_key`	string	The key of the Ruleset used for this transaction.
`outcome`	string	The evaluated outcome for this transaction. Configurable outcomes include \"accept\", \"review\", and \"decline\".
`warnings`	[object]	Describes warnings when bank information is unavailable for the Signal model.
`warning_type`	string	A broad categorization of the warning (safe for programmatic use).
`warning_code`	string	A specific code identifying the warning. Refer to Plaid's error codes documentation. For `ITEM_LOGIN_REQUIRED`, re-authenticate users via Link's update mode to fix credentials and allow data fetching.
`warning_message`	string	A developer-friendly description of the warning type (not safe for programmatic use).

Report ACH Transaction

This endpoint is used to report whether the transaction was initiated.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
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	string	Must be the same as the `client_transaction_id` supplied when calling /signal/evaluate Min length: 1 Max length: 36
initiated	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.

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
request_id	string	A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Return Report on ACH Transaction

This API endpoint to report a returned transaction that was previously sent to the /signal/evaluate endpoint.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Types	Require	Description
client_id	string	Yes	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	yes	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	string	yes	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	string	yes	Must be a valid ACH return code (e.g. \"R01\") If formatted incorrectly, this will result in an INVALID_FIELD error.

Response Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
request_id	string	A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Opt-in-an-item-to-signal

This endpoint is used to opt-in an Item to the Signal data collection process, developing a Signal score when an Item is not initialized with Signal.

Request Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
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	string	The access token associated with the Item data is being requested for.

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
request_id	string	A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Reference guide for the Signal product

Endpoints Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoints	Description
`/signal/evaluate`	Retrieve Signal scores
`/signal/decision/report`	Report whether you initiated an ACH transaction
`/signal/return/report`	Report a return for an ACH transaction
`/signal/prepare`	Add Signal to a newly linked item

","_postman_id":"35351e46-de78-4217-8fa0-bfe78f0a186e","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}},{"name":"Transfer","item":[{"name":"Initiating transfers","item":[{"name":"Create a transfer authorization","id":"fdfb6d16-7ddd-43d2-9826-ec4284a0f69c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"access_token\": {{access_token}},\n \"account_id\": {{account_id}},\n \"type\": \"debit\",\n \"network\": \"ach\",\n \"amount\": \"12.34\",\n \"user\": {\n \"legal_name\": \"Makinde Mercy\"\n }\n }","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/transfer/authorization/create","description":"

Create Transfer Authorization

This endpoint is used to authorize a transfer. This endpoint must be called prior to calling /transfer/create.

Request Body Defintion

Parameter	Data Type	Description
`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`	string	Required. The Plaid `access_token` for the account that will be debited or credited.
`account_id`	string	Required. The Plaid `account_id` corresponding to the end-user account that will be debited or credited.
`funding_account_id`	string	Specify the account used to fund the transfer. Should be specified if using legacy funding methods only. If using Plaid Ledger, leave this field blank. Defaults to the `funding_account_id` specified during onboarding if left blank and using legacy funding methods.
`ledger_id`	string	Specify which ledger balance is used to fund the transfer. Defaults to the `id` of the default ledger balance if left blank.
`type`	string	Required. The type of transfer: either `debit` or `credit`.
`network`	string	Required. The network or rails used for the transfer (`ach`, `same-day-ach`, `rtp`, `wire`).
`amount`	string	Required. The transfer amount as a decimal string with two digits of precision (e.g., `\"10.00\"`). For `/transfer/authorization/create`, specify the maximum amount to authorize.
`ach_class`	string	Specifies the use case of the transfer. Required for ACH network transfers. Supported codes: `ccd`, `ppd`, `tel`, `web`.
`wire_details`	object	Information specific to wire transfers. Contains fields like `message_to_beneficiary` (Max: 140 characters).
`user`	object	Required. Information about the account holder, including `legal_name` (required), `phone_number`, `email_address`, and `address` (subfields: `street`, `city`, `region`, `postal_code`, `country`).
`device`	object	Information about the device initiating the authorization (`ip_address`, `user_agent`). These fields are not currently incorporated into the risk check.
`iso_currency_code`	string	The currency of the transfer amount. Default: `\"USD\"`.
`idempotency_key`	string	A random key provided by the client per unique authorization (expires after 48 hours). Used for safely retrying requests without duplicating operations. Max length: 50.
`user_present`	boolean	Indicates if the end user is initiating the transfer themselves (`true`) or if it’s an automatic recurring payment (`false`). Not currently used but supports future functionality.
`originator_client_id`	string	The Plaid client ID that is the originator of this transfer. Only needed when creating transfers on behalf of another client as a Platform customer.
`test_clock_id`	string	Plaid’s unique identifier for a test clock. Used only in the sandbox environment. Specifies the virtual time for the authorization.

Response Body Defintion

Authorization Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Item	Type	Description	Possible Values/Format
`id`	string	Plaid’s unique identifier for a transfer authorization.
`created`	string	The datetime representing when the authorization was created.	Format: `date-time` (e.g., `2006-01-02T15:04:05Z`)
`decision`	string	A decision regarding the proposed transfer.	`approved`, `declined`, `user_action_required`
`decision_rationale`	object	Rationale for Plaid's decision regarding a proposed transfer.	Includes `code` and `description`.
`code`	string	A code representing the rationale for approving or declining the transfer.	`NSF`, `RISK`, `TRANSFER_LIMIT_REACHED`, `MANUALLY_VERIFIED_ITEM`, `ITEM_LOGIN_REQUIRED`, `ERROR`, `MIGRATED_ACCOUNT_ITEM`, `null`
`description`	string	A human-readable description of the code associated with the transfer.

Payment Risk Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Item	Type	Description	Possible Values/Format
`bank_initiated_return_score`	integer	A score (1-99) indicating the risk of a return due to insufficient funds or other issues.	Minimum: 1, Maximum: 99
`customer_initiated_return_score`	integer	A score (1-99) indicating the risk of a return initiated by the customer as unauthorized.	Minimum: 1, Maximum: 99
`risk_level`	string	Comprises five risk categories.	`HIGH_RISK`, `MEDIUM_HIGH_RISK`, `MEDIUM_RISK`, `MEDIUM_LOW_RISK`, `LOW_RISK`

Proposed Transfer Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Item	Type	Description	Possible Values/Format
`ach_class`	string	Specifies the use case of the transfer (required for ACH network transfers).	`ccd`, `ppd`, `tel`, `web`
`account_id`	string	The Plaid account ID for the account to be debited or credited.
`funding_account_id`	string	The ID of the associated funding account.
`type`	string	The type of transfer (`debit` or `credit`).	`debit`, `credit`

User Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Item	Type	Description
`legal_name`	string	The user's legal name.
`phone_number`	string	The user's phone number.
`email_address`	string	The user's email address.
`address`	object	The address associated with the account holder, including `street`, `city`, `region`, `postal_code`, and `country`.

Cancel Transfer Authorization

This endpoint to cancel a transfer authorization.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Types	Description
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	string (required)	Plaid’s unique identifier for a transfer authorization.

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
request_id	string	A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Create Transfer

This endpoint allows you 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.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
`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`	string	The Plaid `access_token` for the account that will be debited or credited. Required.
`account_id`	string	The Plaid `account_id` corresponding to the end-user account that will be debited or credited. Required.
`authorization_id`	string	Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier. Required.
`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.
`description`	string	The transfer description. Maximum of 15 characters. If reprocessing a returned transfer, the `description` field must be `\"Retry 1\"` or `\"Retry 2\"` to indicate retries of previously returned transfers.
`metadata`	object	A mapping of client-provided string fields to any string value. Limitations: values must be strings, ASCII characters only, maximum of 50 key/value pairs, key length up to 40 characters, value length up to 500 characters.
`test_clock_id`	string	Plaid’s unique identifier for a test clock. May only be used in the 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\"`). Must be less than or equal to `transfer.amount`.

Response Body Defintion

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}},"urlObject":{"path":["transfer","create "],"host":["https://sandbox.plaid.com"],"query":[],"variable":[]}},"response":[{"id":"263ec923-53d7-4289-8e44-1a50c58e57ba","name":"Create a transfer","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": \"${PLAID_CLIENT_ID}\",\n \"secret\": \"${PLAID_SECRET}\",\n \"access_token\": {{access_token}},\n \"account_id\": {{account_id}},\n \"authorization_id\": \"231h012308h3101z21909sw\",\n \"description\": \"Payment\"\n}","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/transfer/create "},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transfer\": {\n \"id\": \"460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9\",\n \"authorization_id\": \"c9f90aa1-2949-c799-e2b6-ea05c89bb586\",\n \"ach_class\": \"ppd\",\n \"account_id\": \"3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr\",\n \"funding_account_id\": \"8945fedc-e703-463d-86b1-dc0607b55460\",\n \"ledger_id\": \"563db5f8-4c95-4e17-8c3e-cb988fb9cf1a\",\n \"type\": \"credit\",\n \"user\": {\n \"legal_name\": \"Anne Charleston\",\n \"phone_number\": \"510-555-0128\",\n \"email_address\": \"acharleston@email.com\",\n \"address\": {\n \"street\": \"123 Main St.\",\n \"city\": \"San Francisco\",\n \"region\": \"CA\",\n \"postal_code\": \"94053\",\n \"country\": \"US\"\n }\n },\n \"amount\": \"12.34\",\n \"description\": \"payment\",\n \"created\": \"2020-08-06T17:27:15Z\",\n \"refunds\": [],\n \"status\": \"pending\",\n \"network\": \"ach\",\n \"cancellable\": true,\n \"guarantee_decision\": null,\n \"guarantee_decision_rationale\": null,\n \"failure_reason\": null,\n \"metadata\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n },\n \"origination_account_id\": \"\",\n \"iso_currency_code\": \"USD\",\n \"standard_return_window\": \"2023-08-07\",\n \"unauthorized_return_window\": \"2023-10-07\",\n \"expected_settlement_date\": \"2023-08-04\",\n \"originator_client_id\": \"569ed2f36b3a3a021713abc1\",\n \"recurring_transfer_id\": null,\n \"credit_funds_source\": \"sweep\",\n \"facilitator_fee\": \"1.23\",\n \"network_trace_id\": null\n },\n \"request_id\": \"saKrIBuEB9qJZno\"\n}"}],"_postman_id":"878cb3b9-25a7-4cd0-890d-7f820a6e3771"},{"name":"Cancel a transfer","id":"2ab3505f-4c7b-4838-8766-eee0f8512399","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\": {{client_id}},\n \"secret\": {{secret}},\n \"transfer_id\": \"123004561178933\"\n }","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/transfer/cancel ","description":"

Transfer Cancellation

This endpoint allows the client to cancel a specific transfer.

Request Body

Transfer Request Fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description	Additional Notes
`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.	Required.
`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.
transfer_id	string	Plaid’s unique identifier for a transfer.	required

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
request_id	string	A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API reference for Transfer initiation endpoints

Endpoint Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoint	Overview
`/transfer/authorization/create`	Create a transfer authorization
`/transfer/authorization/cancel`	Cancel a transfer authorization
`/transfer/create`	Create a transfer
`/transfer/cancel`	Cancel a transfer

","_postman_id":"3c30a9db-239c-4a8c-beb1-f79adb85ec77","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}},{"name":"Reading Transfers and Transfer events","item":[{"name":"Retrieve a transfer","id":"af0e132a-6c0c-4e26-9cb1-2cfbef55ebe5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"client_id\":{{client_id}},\n \"secret\": {{secret}},\n \"transfer_id\": \"460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9\"\n }","options":{"raw":{"language":"json"}}},"url":"https://sandbox.plaid.com/transfer/get ","description":"

The endpoint is used 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 Body Defintion.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
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.

Response Defintion

The response for this request is a JSON object with the following properties:

Key	Data Type	Description
transfer (object)	Object	An object containing detailed information about the transfer.
account_id	string	The ID of the account associated with the transfer.
funding_account_id	string	The ID of the funding account for the transfer.
ledger_id	string	The ledger ID for the transfer.
ach_class	string	The ACH class for the transfer.
amount	string	The amount of the transfer.
cancellable	boolean	Indicates whether the transfer is cancellable.
created	string	The creation timestamp of the transfer.
description	string	Description of the transfer.
failure_reason (object)	Object	Details about the failure reason, including ACH return code and description.
id	string	The unique identifier of the transfer.
metadata (object)	Object	Additional metadata associated with the transfer.
network	string	The network associated with the transfer.
status	string	The status of the transfer.
type	string	The type of the transfer.
iso_currency_code	string	The ISO currency code for the transfer.
standard_return_window	string	The standard return window for the transfer.
unauthorized_return_window	string	The unauthorized return window for the transfer.
expected_settlement_date	string	The expected settlement date for the transfer.
user (object)	Object	Details about the user associated with the transfer, including email, legal name, phone number, and address.
recurring_transfer_id	string	The ID of the recurring transfer, if applicable.
credit_funds_source	string	The source of credit funds for the transfer.
facilitator_fee	string	The facilitator fee for the transfer.
request_id	string	The request ID associated with the response.

This endpoint allows you 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 Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
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 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 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.

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
id	string	Plaid’s unique identifier for a transfer.
authorization_id	string	Plaid’s unique identifier for a transfer authorization.
ach_class	string	Specifies the use case of the transfer (e.g., ccd, ppd, tel, web for ACH network).
account_id	string	The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id	nullable string	The id of the associated funding account.
ledger_id	nullable string	Plaid’s unique identifier for a Plaid Ledger Balance.
type	string	The type of transfer: debit or credit.
user	object	The legal name and other information for the account holder.
legal_name	string	The user's legal name.
phone_number	nullable string	The user's phone number.
email_address	nullable string	The user's email address.
address	nullable object	The address associated with the account holder.
street	nullable string	The street number and name.
city	nullable string	Example: \"San Francisco\"
region	nullable string	The state or province (e.g., \"CA\").
postal_code	nullable string	The postal code (e.g., \"94103\").
country	nullable string	A two-letter country code (e.g., \"US\").
amount	string	The amount of the transfer (decimal string with two digits of precision).
description	string	The description of the transfer.
created	string	The datetime when this transfer was created.
status	string	The status of the transfer: pending, posted, settled, funds_available, cancelled, failed, returned.
sweep_status	nullable string	The status of the sweep for the transfer: unswept, swept, swept_settled, return_swept.
network	string	The network or rails used for the transfer: ach, same-day-ach, rtp, wire.
wire_details	nullable object	Information specific to wire transfers.
message_to_beneficiary	nullable string	Additional information from the wire originator to the beneficiary.
cancellable	boolean	Indicates if the transfer can still be cancelled.
failure_reason	nullable object	The failure reason if the event type for a transfer is \"failed\" or \"returned\". Null value otherwise.
ach_return_code	nullable string	The ACH return code, e.g., R01.
metadata	nullable object	The Metadata object is a mapping of client-provided string fields to any string value.
iso_currency_code	string	The currency of the transfer amount, e.g., \"USD\".
standard_return_window	nullable string	The date 3 business days from settlement date indicating the ACH returns can no longer happen.
unauthorized_return_window	nullable string	The date 61 business days from settlement date indicating certain ACH returns can no longer happen.
expected_settlement_date	nullable string	The date when settlement will occur between Plaid and the receiving bank (RDFI).
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.
refunds	object	A list of refunds associated with this transfer.
id	string	Plaid’s unique identifier for a refund.
transfer_id	string	The ID of the transfer to refund.
amount	string	The amount of the refund (decimal string with two digits of precision).
status	string	The status of the refund: pending, posted, cancelled, failed, settled, returned.
failure_reason	nullable object	The failure reason if the event type for a refund is \"failed\" or \"returned\". Null value otherwise.
ach_return_code	nullable string	The ACH return code, e.g., R01.
ledger_id	nullable string	Plaid’s unique identifier for a Plaid Ledger Balance.
created	string	The datetime when this refund was created.
network_trace_id	nullable string	The trace identifier for the transfer based on its network (ACH, rtp, or wire).
recurring_transfer_id	nullable string	The id of the recurring transfer if this transfer belongs to a recurring transfer.
expected_sweep_settlement_schedule	object	The expected sweep settlement schedule of this transfer.
sweep_settlement_date	string	The settlement date of a sweep for this transfer.
swept_settled_amount	string	The accumulated amount that has been swept by the sweep settlement date.
credit_funds_source	nullable string	This field specifies the source of funds for the transfer (deprecated).
facilitator_fee	string	The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee.
network_trace_id	nullable string	The trace identifier for the transfer based on its network.
request_id	string	A unique identifier for the request, which can be used for troubleshooting.

This endpoint is used to get a list of transfer events based on specified filter criteria.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
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 transfers to list. This should be in RFC 3339 format (e.g., 2019-12-06T22:35:49Z).
end_date	string	The end datetime of transfers to list. This should be in RFC 3339 format (e.g., 2019-12-06T22:35:49Z).
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.
event_types	array	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, 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. 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.

Response Body Defintion

Key	Data Type	Description
event_id	integer	Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: 0
timestamp	string	The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z. Format: date-time
event_type	string	The type of event that this transfer represents. Event types with prefix sweep represent events for Plaid Ledger sweeps. 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, refund.pending, refund.cancelled, refund.failed, refund.posted, refund.settled, refund.returned, refund.swept, refund.return_swept.
account_id	string	The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.
funding_account_id	nullable	The id of the associated funding account, available in the Plaid Dashboard.
ledger_id	nullable	Plaid’s unique identifier for a Plaid Ledger Balance.
transfer_id	string	Plaid’s unique identifier for a transfer. This field is null for Plaid Ledger Sweep 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.
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.
failure_reason	nullable	The failure reason if the event type for a transfer is \"failed\" or \"returned\". Null value otherwise.
ach_return_code	nullable	The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned.
description	string	A human-readable description of the reason for the failure or reversal.
sweep_id	nullable	Plaid’s unique identifier for a sweep.
sweep_amount	nullable	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\").
refund_id	nullable	Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id	nullable	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).
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.

This endpoint allows you to request up to the next 25 transfer events that happened after a specific event_id.

Request Body Definition

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
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

Response Body Defintion

This endpoint allow you to fetch a sweep corresponding to the given sweep_id

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
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).

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Data Type	Description
id	string	Identifier of the sweep.
funding_account_id	string	The id of the funding account to use, available in the Plaid Dashboard. This determines which business checking account will be credited or debited.
ledger_id	string	Plaid’s unique identifier for a Plaid Ledger Balance.
created	string	The datetime when the sweep occurred, in RFC 3339 format (date-time).
amount	string	Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g., \"-10.00\"). If absent, the sweep was net-settled to zero.
iso_currency_code	string	The currency of the sweep (e.g., \"USD\").
settled	string	The date when the sweep settled, in the YYYY-MM-DD format.
status	string	The status of the sweep transfer. Possible values: `pending`, `posted`, `settled`, `returned`, `failed`, or `null`.
trigger	string	The trigger for the sweep. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate`.
description	string	The description of the deposit that will be passed to the receiving bank (up to 10 characters).
network_trace_id	string	The trace identifier for the transfer based on its network (ACH, RTP, wire).
request_id	string	A unique identifier for the request, useful for troubleshooting. This identifier is case-sensitive.

This endpoint allows you to fetch sweeps that match the given filters.

Request Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Data Type	Description
client_id	string	Your Plaid API client ID. This is required and may be provided in the `PLAID-CLIENT-ID` header or as part of a request body.
secret	string	Your Plaid API secret. This is required and may be provided in the `PLAID-SECRET` header or as part of a request body.
start_date	string	The start datetime of sweeps to return (RFC 3339 format).
end_date	string	The end datetime of sweeps to return (RFC 3339 format).
count	integer	The maximum number of sweeps to return. Default: 25, Minimum: 1, Maximum: 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. Possible values: `pending`, `posted`, `settled`, `returned`, `failed`, or `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 specified transfer ID.
trigger	string	The trigger for the sweep. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate`.

Response Body Defintion

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Type	Description
id	string	The unique identifier of the sweep.
funding_account_id	string	The ID of the funding account used, available in the Plaid Dashboard, to determine which business checking account is credited or debited.
ledger_id	string?	Plaid’s unique identifier for a Plaid Ledger Balance (nullable).
created	string	The datetime when the sweep occurred, in RFC 3339 format.
amount	string	Signed decimal amount of the sweep (e.g., \"-10.00\"). If not present, the sweep was net-settled to zero.
iso_currency_code	string	The currency of the sweep (e.g., \"USD\").
settled	string?	The date when the sweep settled, in YYYY-MM-DD format (nullable).
status	string?	The status of the sweep transfer. Possible values: `pending`, `posted`, `settled`, `returned`, `failed`, `null`.
trigger	string?	The trigger of the sweep. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate`.
description	string	The description of the deposit that will be passed to the receiving bank (up to 10 characters).
network_trace_id	string?	The trace identifier for the transfer based on its network (nullable). Will be set after the transfer has posted.
request_id	string	A unique identifier for the request used for troubleshooting. This is case-sensitive.

API reference for Transfer read and Transfer event endpoints and webhooks

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Reading Transfers
`/transfer/get`	Retrieve information about a transfer
`/transfer/list`	Retrieve a list of transfers and their statuses
`/transfer/event/list`	Retrieve a list of transfer events
`/transfer/event/sync`	Sync transfer events
`/transfer/sweep/get`	Retrieve information about a sweep
`/transfer/sweep/list`	Retrieve a list of sweeps

\n\n\n\n\n\n\n\n\n\n\n\n\n

Webhooks
`TRANSFER_EVENTS_UPDATE`	New transfer events available

","_postman_id":"ff99afbc-90a7-4711-970b-19b11b984d90","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}}],"id":"64158881-7e7f-43c0-8af9-ade69a7b116d","description":"

API reference for Transfer endpoints and webhooks

Endpoints Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Initiating Transfers
`/transfer/authorization/create`	Create a transfer authorization
`/transfer/authorization/cancel`	Cancel a transfer authorization
`/transfer/create`	Create a transfer
`/transfer/cancel`	Cancel a transfer

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Reading Transfers
`/transfer/get`	Retrieve information about a transfer
`/transfer/list`	Retrieve a list of transfers and their statuses
`/transfer/event/list`	Retrieve a list of transfer events
`/transfer/event/sync`	Sync transfer events
`/transfer/sweep/get`	Retrieve information about a sweep
`/transfer/sweep/list`	Retrieve a list of sweeps

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Account Linking
`/transfer/capabilities/get`	Determine RTP eligibility for a Plaid Item
`/transfer/intent/create`	Create a transfer intent and invoke Transfer UI (Transfer UI only)
`/transfer/intent/get`	Retrieve information about a transfer intent (Transfer UI only)
`/transfer/migrate_account`	Create an Item to use with Transfer from known account and routing numbers

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Recurring Transfers
`/transfer/recurring/create`	Create a recurring transfer
`/transfer/recurring/cancel`	Cancel a recurring transfer
`/transfer/recurring/get`	Retrieve information about a recurring transfer
`/transfer/recurring/list`	Retrieve a list of recurring transfers

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Refunds
`/transfer/refund/create`	Create a refund for a transfer
`/transfer/refund/cancel`	Cancel a refund
`/transfer/refund/get`	Retrieve information about a refund

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Platform Payments
`/transfer/originator/create`	Create a new originator
`/transfer/originator/get`	Get the status of an originator's onboarding
`/transfer/originator/list`	Get the status of all originators' onboarding
`/transfer/originator/funding_account/update`	Update the default funding account of an originator
`/transfer/questionnaire/create`	Generate a Plaid-hosted onboarding UI URL

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Plaid Ledger
`/transfer/ledger/deposit`	Deposit funds into a ledger balance held with Plaid
`/transfer/ledger/distribute`	Move available balance between platform and its originator
`/transfer/ledger/get`	Retrieve information about the ledger balance held with Plaid
`/transfer/ledger/withdraw`	Withdraw funds from a ledger balance held with Plaid

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Program Metrics
`/transfer/metrics/get`	Get transfer product usage metrics
`/transfer/configuration/get`	Get transfer product configuration

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Sandbox
`/sandbox/transfer/simulate`	Simulate a transfer event
`/sandbox/transfer/refund/simulate`	Simulate a refund event
`/sandbox/transfer/sweep/simulate`	Simulate creating a sweep
`/sandbox/transfer/fire_webhook`	Simulate a transfer webhook
`/sandbox/transfer/ledger/deposit/simulate`	Simulate a deposit sweep event
`/sandbox/transfer/ledger/simulate_available`	Simulate converting pending balance into available balance
`/sandbox/transfer/ledger/withdraw/simulate`	Simulate a withdrawal sweep event
`/sandbox/transfer/test_clock/create`	Create a test clock
`/sandbox/transfer/test_clock/advance`	Advance a test clock
`/sandbox/transfer/test_clock/get`	Retrieve information about a test clock
`/sandbox/transfer/test_clock/list`	Retrieve a list of test clocks

","_postman_id":"64158881-7e7f-43c0-8af9-ade69a7b116d","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","name":"Payments & Funding","type":"folder"}}}],"id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"d76c1be3-5a62-4d09-81ba-5c226321e607","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"d6e26826-5430-4ab6-9776-0c16c69fcd0a","type":"text/javascript","packages":{},"exec":[""]}}],"_postman_id":"409e2350-d2ce-4166-a365-1fbd36c7c41d","description":""}],"event":[{"listen":"prerequest","script":{"id":"18c8b320-4e0b-4123-88cd-9ceca6b04b70","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"ac86ef9a-32d3-43d0-8980-205eb2ea00f7","type":"text/javascript","packages":{},"exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://sandbox.plaid.com","type":"string"}]}