Legacy API Documentation

Overview

Introduction

Welcome to Plaid! Here you will find information on how to integrate with and use the Plaid API. We've tried to make this documentation user-friendly and example-filled, but please drop us a line with any questions. If you're planning to use our API in production, you should take a look at our privacy policy.

The quickest way to get your integration up and running is to use Plaid Link: a secure, drop-in module that handles credential validation, multi-factor authentication, and error handling for each institution that we support, all while preventing credentials from ever hitting your server. Check out a demo.

The Plaid API uses standard HTTP verbs to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Plaid API is served over HTTPS to ensure data privacy; HTTP is not supported. Every request must include your client_id and secret, except those sent to the Institution or Category endpoints. Request data can be included in either the body or query string, though using the body is recommended.

API Host

https://tartan.plaid.com/ (development)
https://api.plaid.com/ (production)

The development environment supports both live and test accounts. All testing should be done on tartan.plaid.com, as all requests to api.plaid.com will be billed. If you are getting ready to launch into production, please request production API access via the dashboard.

Resource URL Patterns:

/connect
/auth
/balance
/info
/income
/risk
/upgrade
/institutions
/categories

Gaining Access

To gain access to the Plaid API, please create an account on our dashboard. Upon completion of the signup process and acknowledgement of our terms, you will be provided with a live client_id and secret on the dashboard.

Once you receive your client_id and secret, get started by adding a user and getting back transaction data. Simply send a request with the quickstart parameters, and you'll receive 30 days of transactions for the user.

Quickstart

Add account and get transactions:

https://tartan.plaid.com/connect (POST)

Sample Request:

curl -X POST https://tartan.plaid.com/connect \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=wells

Expected Response:

http code 200

{
  "accounts": [
    {
      "_id": "YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo",
      "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
      "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
      "balance": {
        "available": 9930,
        "current": 2275.58
      },
      "institution_type": "fake_institution",
      "meta": {
        "name": "Plaid Gold Checking",
        "number": "3002"
      },
      "subtype": "checking",
      "type": "depository"
    },
...],
  "transactions": [
    {
      "_account": "YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo",
      "_id": "600r0LrVvViXjq96lBpdtyOWboBvzmsaZoeaV",
      "amount": 12.74,
      "date": "2016-03-12",
      "name": "Golden Crepes",
      "meta": {
        "location": {
          "address": "262 W 15th St",
          "city": "New York",
          "state": "NY",
          "zip": "10011",
          "coordinates": {
            "lat": 40.740352,
            "lon": -74.001761
          }
        }
      },
      "pending": false,
      "type": {
        "primary": "place"
      },
      "category": [
        "Food and Drink",
        "Restaurants"
      ],
      "category_id": "13005000",
      "score": {
        "location": {
          "address": 1,
          "city": 1,
          "state": 1
        },
        "name": 0.9
      },
    },
...],
  "access_token": "test"
}

Sandbox

Our development environment works with both test user credentials and live accounts. The following test credentials allow access to the full API without the use of any real credentials:

Credentials: The username plaid_test will return standard responses, and the username plaid_selections will force a selections MFA response for applicable institutions. All passwords except for plaid_good and plaid_locked will return as invalid. In certain cases, depending on the Financial Institution, you might be required to submit additional information in the credentials object such as a PIN number. For more details regarding these institution-specific requirements, check out our institutions endpoint.

MFA: Valid MFA responses are listed below; all other responses will return as invalid. For institutions requiring multiple-question MFA, respond with again for each initial question and tomato for the final question.

Key Description
questions again (for multiple questions), tomato (for final response)
code-based 1234
selections tomato (when available), ketchup (when available)

Test User Credentials

API Key:

id:           test_id
secret:       test_secret
access_token: test_{TYPE} (test_amex, test_wells, etc)

Credentials:

username:     plaid_test (standard)
              plaid_selections (selections mfa)

password:     plaid_good (correct)
              plaid_locked (locked)

pin:          1234

Response Codes

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by block. In general, 200 HTTP codes correspond to success, 40X codes are for client-related failures, and 50X codes are for Plaid-related issues. For a full list of response codes, see response code detail below. We are always working to minimize API errors related to Plaid integrations and address connectivity issues across bank infrastructure. The best resource related to error code resolution is the Plaid Help Center.

HTTP Code Message Resolve
400 1000 access_token missing You need to include the access_token that you received from the original submit call.
400 1001 type missing You need to include a type parameter. Ex. bofa, wells, amex, chase, citi, etc.
400 1003 access_token disallowed You included an access_token on a submit call - this is only allowed on step and get routes.
400 1008 unsupported access_token This access token format is no longer supported. Contact support to resolve.
400 1004 invalid options format Options need to be JSON or stringified JSON.
400 1005 credentials missing Provide username, password, and pin if appropriate.
400 1006 invalid credentials format Credentials need to be JSON or stringified JSON.
400 1007 upgrade_to required In order to upgrade an account, an upgrade_to field is required , ex. connect
400 1009 invalid content-type Valid 'Content-Type' headers are 'application/json' and 'application/x-www-form-urlencoded' with an optional 'UTF-8' charset.
401 1100 client_id missing Include your Client ID so we know who you are.
401 1101 secret missing Include your Secret so we can verify your identity.
401 1102 secret or client_id invalid The Client ID does not exist or the Secret does not match the Client ID you provided.
401 1104 unauthorized product Your Client ID does not have access to this product. Contact us to purchase this product.
401 1105 bad access_token This access_token appears to be corrupted.
401 1106 bad public_token This public_token is corrupt or does not exist in our database. See the Link docs.
401 1107 missing public_token Include the public_token received from the Plaid Link module. See the Link docs.
401 1108 invalid type This institution is not currently supported.
401 1109 unauthorized product The sandbox client_id and secret can only be used with sandbox credentials and access tokens. See Sandbox docs.
401 1110 product not enabled This product is not enabled for this item. Use the upgrade route to add it.
401 1111 invalid upgrade Specify a valid product to upgrade this item to.
401 1112 addition limit exceeded You have reached the maximum number of additions. Contact us to raise your limit.
429 1113 rate limit exceeded You have exceeded your request rate limit for this product. Try again soon.
401 1114 unauthorized environment Your Client ID is not authorized to access this API environment. Contact support@plaid.com to gain access.
401 1115 product already enabled The specified product is already enabled for this item. Call the corresponding product endpoint directly.
402 1200 invalid credentials The username or password provided were not correct.
402 1201 invalid username The username provided was not correct.
402 1202 invalid password The password provided was not correct.
402 1203 invalid mfa The MFA response provided was not correct.
402 1204 invalid send_method The MFA send_method provided was invalid. Consult the documentation for the proper format.
402 1205 account locked The account is locked. Prompt the user to visit the issuing institution's site and unlock their account.
402 1206 account not setup The account has not been fully set up. Prompt the user to visit the issuing institution's site and finish the setup process.
402 1207 country not supported We're United States-only at this point!
402 1208 mfa not supported This account requires a form of MFA that is not currently supported. Other accounts at this institution with a different form of MFA may be supported.
402 1209 invalid pin The pin provided was not correct.
402 1210 account not supported This account is currently not supported.
402 1211 bofa account not supported The security rules for this account restrict access. Disable 'Extra Security at Sign-In' in your Bank of America settings.
402 1212 no accounts No valid accounts exist for this user.
402 1213 invalid patch username The username in a PATCH request must match the username provided in the initial add user POST request.
402 1215 mfa reset MFA access has changed or this application's access has been revoked. Submit a PATCH call to resolve.
401 1218 mfa not required This item does not require the MFA process at this time.
402 1219 wells account not supported The security rules for this account restrict access. Disable 'Enhanced Sign On' in your Wells Fargo settings.
404 1300 institution not available This institution is not yet available in this environment.
404 1301 unable to find institution Double-check the provided institution ID.
402 1302 institution not responding The institution is failing to respond to our request, if you resubmit the query the request may go through.
402 1303 institution down The institution is down for an indeterminate amount of time, if you resubmit in a couple hours it may go through.
402 1304 invalid institution paging parameters Paging parameters must include a non-negative integer 'offset' and positive integer 'count'
402 1305 invalid institution query parameters Query parameters must include a non-empty query string
402 1307 institution no longer supported This institution is no longer supported by our longtail partner.
404 1501 unable to find category Double-check the provided category ID.
400 1502 type required You must include a type parameter.
400 1503 invalid type The specified type is not supported.
400 1507 invalid date Consult the documentation for valid date formats.
404 1600 product not found This product doesn't exist yet, we're actually not sure how you reached this error...
404 1601 product not available This product is not yet available for this institution.
404 1605 user not found User was previously deleted from our system.
404 1606 account not found The account ID provided was not correct.
404 1610 item not found No matching items found; go add an account!
501 1700 extractor error We failed to pull the required information from the institution - make sure the user can access their account; we have been notified.
502 1701 extractor error retry We failed to pull the required information from the institution - resubmit this query.
500 1702 plaid error An unexpected error has occurred on our systems; we've been notified and are looking into it!
503 1800 planned maintenance Portions of our system are down for maintenance. This route is inaccessible. GET requests to Auth and Connect may succeed.

Response Codes

HTTP Response Codes

200: Success
201: MFA Required
400: Bad Request
401: Unauthorized
402: Request Failed
404: Cannot be Found
50X: Server Error

Error Code Details

100X: Bad Request
110X: Unauthorized
120X: User Authentication Invalid
130X: Institutions Error
140X: Entities Error
150X: Categories Error
160X: Item Missing
170X: Server Error
180X: Planned Maintenance

Example Error Message

http code 402
{
  "code": 1200
  "message": "invalid credentials",
  "resolve": "The username or password provided is not correct."
}

Storing API Response data

The access_token returned in a code 200 or 201 Plaid API response provides a secure way to access transaction and account data, and you should securely store the access tokens you generate.

Plaid API responses also include a unique request identifier. A request id is generated even when something goes wrong, so we recommend persisting this value for internal logging purposes, as well as for support-related escalations. More information about how to access a request id can be found in the Plaid Help Center.

Connect

Data Overview

The /connect endpoint allows developers to receive user-authorized transaction and account data. Data is contained in a set of transaction and account objects, one for each respective entry. Transaction data is standardized across financial institutions, and in most cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.

Account data elements

Key Description
_id The unique id of the account.
_item An id unique to the accounts of a particular access token.
balance The Current Balance is the total amount of funds in the account. The Available Balance is the Current Balance less any outstanding holds or debits that have not yet posted to the account. Note that not all institutions calculate the Available Balance. In the case that Available Balance is unavailable from the institution, Plaid will either return an Available Balance value of null or only return a Current Balance.
meta Additional information pertaining to the account such as the limit, name, or last few digits of the account number.
institution_type The financial institution associated with the account. See financial institutions.
type See account types.
subtype A more detailed classification of the account type. When unavailable, this field will not be returned. See subtypes for a list of common subtype values.

Transaction data elements

Key Description
_id The unique id of the transaction.
_account The id of the account in which this transaction occurred.
category_id The id of the category to which this transaction belongs. See category.
score A numeric representation of our confidence in the meta data we attached to the transaction. In the case of a score <.9 we will default to guaranteed and known information.
type Place, Digital, Special, or Unresolved.
amount The settled dollar value. Positive values when money moves out of the account; negative values when money moves in. For example, purchases are positive; credit card payments, direct deposits, refunds are negative.
date The date that the transaction took place in ISO 8601 format.
category An hierarchical array of the categories to which this transaction belongs. See category.
meta See meta details.
pending When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount) may change before they are settled.
_reference_number A unique attribute that is used by the bank/payment processor to identify transactions—where applicable.
_pendingTransaction The id of a posted transaction's associated pending transaction—where applicable.

Connect Meta Options

Key Description
location Detailed merchant location data including address, city, state, zip code, and geo-coordinates where available.

Example Account Data

"accounts": [
  {
    "_id": "YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo",
    "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
    "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
    "balance": {
      "available": 7205.23,
      "current": 7255.23
    },
    "institution_type": "fake_institution",
    "meta": {
      "name": "Plaid Gold Checking",
      "number": "1234"
    },
    "type": "depository",
    "subtype": "checking"
  },
  {
    "_id": "pJPM4LMBNQFrOwp0jqEyTwyxJQrQbgU6kq37k",
    "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
    "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
    "balance": {
      "available": 9930,
      "current": 2275.58
    },
    "institution_type": "fake_institution",
    "meta": {
      "limit": 12500,
      "name": "Plaid Credit Card",
      "number": "3002"
    },
    "type": "credit",
    "subtype": "credit card"
...]

Example Transaction Data

"transactions": [
  {
    "_account": "YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo",
    "_id": "600r0LrVvViXjq96lBpdtyOWboBvzmsaZoeaV",
    "amount": 12.74,
    "date": "2016-03-12",
    "name": "Golden Crepes",
    "meta": {
      "location": {
        "address": "262 W 15th St"
        "city": "New York",
        "state": "NY",
        "zip": "10011",
        "coordinates": {
          "lat": 40.740352,
          "lon": -74.001761
        }
      }
    },
    "pending": false,
    "type": {
      "primary": "place"
    },
    "category": [
      "Food and Drink",
      "Restaurants"
    ],
    "category_id": "13005000",
    "score": {
      "location": {
        "address": 1,
        "city": 1,
        "state": 1
      },
      "name": 0.9
    },
  },
...],

User Flow

The process to add a new end-user is handled through the /connect endpoint and is composed of two primary steps: authentication and data collection. Every call requires a valid client_id and secret, and each end-user is identified with a unique access_token.

Authentication is handled using an end-users's online username and password. Select institutions may also require additional MFA credentials. To add a user, first submit the credentials and institution type (amex, bofa, chase, etc.). The response will contain a success message with the new user's access_token or an authentication notification with a prompt for MFA credentials. If additional MFA credentials are required, submit MFA answers with a request to the /connect/step endpoint.

Using the submit options, transactional data can be collected directly from the original authentication request. Plaid refreshes transactional data multiple times per day from the financial institution. To collect the most up-to-date data we have, simply make a call to the /connect/get endpoint with the user's access_token.

Sample User Flow

Authenticate user           POST: /connect
Submit MFA credential(s)    POST: /connect/step
Get transactions            POST: /connect/get

Add Connect User

To add a new end-user, submit their institution type and credentials to the /connect endpoint. In certain cases, depending on the Financial Institution, you might be required to submit additional information in the credentials object such as a PIN number. For more details regarding these institution-specific requirements, view the credentials link below or check out our institutions endpoint.

Once Plaid receives this data, we will verify the credentials and return a success, failure, or MFA notification, usually in under five seconds. Included in the success notification is an access_token that is required to access that user's data.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
type required The institution code that you want to access.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
options optional See submit options.
Option Type Details
webhook string default is null
only relevant if login_only is true

This webhook will be hit when the users' transactions have finished processing. See webhook.
pending boolean default is false
If set to true, pending transactions will be returned. Pending transactions will generally show up as posted within one to three business days, depending on the type of transaction - though some transactions may never post. Currently, new transaction IDs will be generated for all posted transactions.
login_only boolean default is false
This option is valid for the initial authentication only. If set to false, the initial /connect request will return transaction data based on the start_date and end_date specified.
list boolean default is false
If the institution requires a code-based MFA credential, this option will list the available send methods. For example, Email (ex a...z@plaid.com), Text (ex 123-...-4321). See Code-Based MFA for more details.
start_date string default is 30 days ago
The start date from which to return transactions. ISO 8601 dates are accepted, e.g. '2016-03-01'. It is strongly recommended that you do not pull more than 60 days.
end_date string default is today
The end date to which transactions will be collected.

Upon successfully adding a user, Plaid automatically initiates a process to collect, parse, and clean all of the user's transactions over the next 30-240 seconds.

Add Connect User

/connect (POST)

Add Connect User Submit

curl -X POST https://tartan.plaid.com/connect \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=wells \
  -d options='{
       "webhook":"http://requestb.in/",
       "login_only":true }'

Add Connect User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "transactions": [
    {object},
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Webhook

You can submit a webhook to receive notifications once a user's transactions have been processed and are ready for use. Webhooks are also used to communicate certain errors such as invalid user credentials or an account being locked by the institution. Plaid returns a number of different webhook responses:

Code Details
0 Occurs once the initial transaction pull has finished.
1 Occurs once the historical transaction pull has completed, shortly after the initial transaction pull.
2 Occurs at set intervals throughout the day as data is updated from the financial institutions.
3 Occurs when transactions have been removed from our system.
4 Occurs when an user's webhook is updated via a PATCH request without credentials.
Other Triggered when an error has occurred. Includes the relevant Plaid error code with details on both the error type and steps for error resolution.

The webhook must be in the standard format of http(s)://(www.)domain.com/. The response will contain a corresponding success message and code along with the same access_token that was returned in the initial call (examples on the right). Once the transaction processing has finished, you can use the access_token to collect the full account and transaction information for that user.

All successful webhook responses will be returned a corresponding code, brief message, the number of total transactions, as well as the access token associated with the account. Errors will return with an error code, descriptive message, access token, and a resolve message prompting the steps required to resolve the error. For a list of all possible error codes, check out Response Code Detail or get a detailed view on our GitHub page.

Webhook Body

Initial Transaction Webhook

{
 "message": "Initial transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 0
}

Historical Transaction Webhook

{
 "message": "Historical transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 1
}

Normal Transaction Webhook

{
 "message": "Normal transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 2
}

Removed Transaction Webhook

{
 "message": "Transactions removed",
 "access_token": "xxxxx",
 "removed_transactions": [
   "53dff5c470ae103f1c1c3523",
   "53dff5cb70ae103f1c1c3524"
 ],
 "code": 3
}

User's Webhook Updated

{
 "message": "Webhook acknowledged",
 "access_token": "xxxxx",
 "code": 4
}

Error Response Webhook Example

{
 "message": "account locked",
 "resolve": "The account is locked. Please prompt the user to visit the issuing institution's site and unlock their account.",
 "access_token": "xxxxx",
 "code": 1205
}

Single Request Data

If you'd like to add a user and receive transactional data in one request, there is an additional flow to allow this governed by the login_only option. To receive 30 days of transactional data following the initial user submit, simply remove the login_only flag as it will default to false. To specify the length of history returned, you can use the start_date and end_date parameters. All of these parameters should be contained in the options object of the initial request.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
type required The institution code that you want to access.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
options optional See submit options.
Option Type Details
login_only boolean default is false
This option is valid for the initial authentication only. If set to false, the initial /connect request will return transaction data based on the start_date and end_date specified.
start_date string default is 30 days ago
The start date from which to return transactions. ISO 8601 dates are accepted, e.g. '2016-03-01'. It is strongly recommended that you do not pull more than 60 days.
end_date string default is today
The end date to which transactions will be collected.

This flow is good for initial setup, but is not recommended in production as it causes end-user delays and is heavy on both the client and server. The amount of time pulled is proportional to the time it takes to complete. Please do not try anything longer than 60 days on the first pull, a full transaction pull for all of the available data is executed within 5 minutes and available via a POST request to the /connect/get endpoint.

Single Request Submit

curl -X POST https://tartan.plaid.com/connect \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=wells

Single Request Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "transactions": [
    {object},
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Connect MFA

Some banks require multi-factor authentication (MFA) and the /connect/step route is built to submit the additional information needed. Users are first submitted via the standard Add Connect User process, and the MFA data is sent through an additional request to the /connect/step route.

Plaid is actively working to reduce the MFA requirements for users at the financial institutions we support. As such, we recommend building your integration with the expectation that MFA is always a possibility, but not always required.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
mfa required The extra information needed in the format: {mfa:'xxxxx'}.

The mfa parameter is not required when specifying a MFA send_method in the request options.
access_token required The ACCESS_TOKEN returned when the user was added.
options optional See MFA options.
MFA Options Details
send_method object Default is first available email
For Code-Based MFA only, you may specify a type {"type":"phone"} or one of the returned masks {"mask":"123-...-4321"} that were returned by the initial {"list":true} submit call. For more details, see the Code-Based MFA section below.

Question-Based MFA

Question-based authentication (type=questions) requires the user to answer a security question. With some financial institutions, multiple security questions may be required. To handle multiple security questions, it is recommended that you continue to post to the route until an http code 200 is received.

Code-Based MFA

Some institutions require an MFA code that is sent to your email or phone. If there are multiple potential delivery methods, we allow you to specify which you'd like to use. To see a list of delivery options, specify {"list":true} in the options object of the original /connect submit call.

After receiving the list of delivery options (as shown on the right), you may specify the delivery method by sending {"send_method":{"type":"phone"}} in the options object of your call to the /connect/step endpoint. When multiple options exist for a particular send method, you may specify the phone number, email, etc. by sending in the mask. For example: {"send_method":{"mask":"xxx-xxx-1234"}}

If no delivery option is specified, Plaid will default to the first email returned by the financial institution.

Connect MFA

/connect/step (POST)

MFA Credential Submit

curl -X POST https://tartan.plaid.com/connect/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Question-Based MFA

http code 201
{
  "type": "questions",
  "mfa": [{"question":"What was the name of your first pet?"}],
  "access_token": "xxxxx"
}

Code-based MFA (Delivery Options)

To see a full list of code delivery options, include "list":true in the options object of the original Add Connect User call.

curl -X POST https://tartan.plaid.com/connect \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=chase \
  -d options='{"list":true}'

A successful response will include various send methods, if available.

http code 201
{
  "type": "list",
  "mfa": [
    {"mask":"t..t@plaid.com", "type":"email"},
    {"mask":"xxx-xxx-5309", "type":"phone"}
  ],
  "access_token": "xxxxx"
}

Code-based MFA (Choice Confirmation)

If there are multiple delivery options for the MFA code, you can specify if you'd like to receive the code by phone, email, etc.

curl -X POST https://tartan.plaid.com/connect/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"type":"phone"}}'

Or specify a specific phone number, email, etc. if applicable.

curl -X POST https://tartan.plaid.com/connect/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"mask":"xxx-xxx-5309"}}'

Once a delivery option has been chosen and submitted via the /step route, you will receive confirmation that the code has been sent.

http code 201
{
  "type": "device",
  "mfa": {
    "message": "Code sent to xxx-xxx-5309"
  },
  "access_token": "xxxxx"
}

The MFA code can then be submitted

curl -X POST https://tartan.plaid.com/connect/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d mfa=1234

Get Transactions

After a user is added, Plaid begins a process to collect, parse, and clean all of the user's historical transactions over the next 30-240 seconds. If a webhook is provided, you will get a notification as soon as that process is complete. Following that time, we will update the user's data at set intervals throughout the day to collect all of the most recent transactions. A user's account and transaction data may be retrieved at any time from our servers.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN returned when the user was added.
options optional See get options.
Option Type Details
pending boolean default is false
If set to true, transactions from account activities that have not yet posted to the account will be returned. Pending transactions will generally show up as posted within one to three business days, depending on the type of transaction.
account string Collect transactions for a specific account only, using an account _id returned from the original Add Connect User submission.
gte date Collect all recent transactions since and including the given date.
lte date Collect all transactions up to and including the given date. Can be used with gte to define a range.

Full History Update

Within five minutes of when we finish the initial add—we will pull all the available transactional history for the user, regardless of the original dates specified in the original call.

Limitations

We work hard to provide as much historical data as possible, however there are limiting factors in the amount of information an institution holds and the length of time a user has had their account. To see more information on data availability by institution, please visit our GitHub page.

We update a users account at set intervals throughout the day, independent of how many times a client calls the /connect endpoint. We pull transactions as they are posted to the issuing institution. Dependent on the merchant acquirer, processor, gateway and issuer, the time from when a transaction occurs to when it is posted can take from a couple minutes to a couple days. The date in the transaction will be as close to the original transaction date as possible.

Get Transactions

/connect/get (POST)

Get Transactions Submit

curl -X POST https://tartan.plaid.com/connect/get \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Get Transactions Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "transactions": [
    {object},
    {object}
  ]
}

Update Connect User

When a user changes their password or MFA credentials with a financial institution or is locked out of their account, they must update their credentials with Plaid as well. To do so, send a PATCH request with the updated credentials. If multi-factor authentication (MFA) is required, send additional PATCH requests to the /connect/step route as needed.

PATCH may also be used to update the webhook associated with a particular user. A PATCH request submitted without credentials but with a webhook will trigger a confirmation webhook.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
access_token required The ACCESS_TOKEN of the user you wish to update.

Update Connect User

/connect (PATCH)

Update Connect User Submit

curl -X PATCH https://tartan.plaid.com/connect \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d username=plaid_test \
  -d password=plaid_good \
  -d access_token={ACCESS_TOKEN}

Update Connect User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "transactions": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Update Connect User Submit (MFA)

curl -X PATCH https://tartan.plaid.com/connect/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Update Connect User Webhook

curl -X PATCH https://tartan.plaid.com/connect \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"webhook":"http://requestb.in"}'

Delete Connect User

This will remove a user from your account, as specified by a particular access_token. This process is irrevocable. You may add the user again using the Add Connect User process, but a new access_token will be generated.

To remove a user, send a request with the following parameters. These can be sent in as a query string or in the body.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN that you wish to be removed from your account.

Delete Connect User

/connect (DELETE)

Delete Connect User Submit

curl -X DELETE https://tartan.plaid.com/connect \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Delete Connect User Response

http code 200
{
   "message": "Successfully removed from your account"
}

Auth

Auth Overview

The /auth endpoint allows you to collect a user's bank account and routing number, along with basic account data and balances. The product performs two crucial functions—it translates bank access credentials (username & password) into an accurate account and routing number. No input of account or routing number is necessary. Secondly it validates that this is the owner of this account number, in a NACHA compliant manner. No need for micro-deposits or any other secondary authentication.

Add Auth User

To collect a user's bank account and routing info, send a request with the following parameters. In certain cases, depending on the Financial Institution, you might be required to submit additional information in the credentials object such as a PIN number. For more details regarding these institution-specific requirements, view the credentials link below or check out our institutions endpoint.

Once Plaid receives this data, we will verify the credentials and return a success, failure, or MFA notification, usually under five seconds. Included in the success notification is an ACCESS_TOKEN that is required to access that users' data.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
type required The institution code that you want to access.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin USAA only Pin number required only for USAA accounts.
options optional See auth options.
Option Type Details
list boolean default is false
If the institution requires a code-based MFA credential, this option will list the available methods. For example, Email (ex a...z@plaid.com), Text (ex 123-...-4321). See MFA for more details.

Add Auth User

/auth (POST)

Add Auth User Submit

curl -X POST https://tartan.plaid.com/auth \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=wells

Add Auth User Response

http code 200
{
  "accounts": [
    {
      "_id": "mjj9jp92z2fD1mLlpQYZI1gAd4q4LwTKmBNLz",
      "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
      "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
      "balance": {
        "available": 1203.42,
        "current": 1274.93
      },
      "meta": {
        "name": "Plaid Savings",
        "number": "9606"
      },
      "numbers": {
        "routing": "021000021",
        "account": "9900009606",
        "wireRouting": "021000021"
      },
      "institution_type": "fake_institution",
      "type": "depository"
    },
  ...],
  "access_token": "xxxxx"
}

Auth MFA

Some banks require multi-factor authentication (MFA) and the /auth/step route is built to submit the additional information needed. Users are first submitted via the standard Add Auth User process, and the MFA data is sent through an additional request to the /auth/step route.

Plaid is actively working to reduce the MFA requirements for users at the financial institutions we support. As such, we recommend building your integration with the expectation that MFA is always a possibility, but not always required.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
mfa required The extra information needed in the format: {mfa:'xxxxx'}.

The mfa parameter is not required when specifying a MFA send_method in the request options.
access_token required The access_token is returned when the user is added.
options optional Add these MFA options to the original options from the Add Auth User request as necessary.
MFA Options Details
send_method object Default is first available email
For Code-Based MFA only, you may specify a type {"type":"phone"} or one of the returned masks {"mask":"123-...-4321"} that were returned by the initial {"list":true} submit call. For more details, see the Code-Based MFA section below.

Question-Based MFA

Question-based authentication (type=questions) requires the user to answer a security question. With some financial institutions, multiple security questions may be required. To handle multiple security questions, it is recommended that you continue to post to the route until an http code 200 is received.

Code-Based MFA

Some institutions require an MFA code that is sent to your email or phone. If there are multiple potential delivery methods, we allow you to specify which you'd like to use. To see a list of delivery options, specify {"list":true} in the options object of the original /auth submit call.

After receiving the list of delivery options (as shown on the right), you may specify the delivery method by sending {"send_method":{"type":"phone"}} in the options object of your call to the /auth/step endpoint. When multiple options exist for a particular send method, you may specify the phone number, email, etc. by sending in the mask. For example: {"send_method":{"mask":"xxx-xxx-1234"}}

If no delivery option is specified, Plaid will default to the first email returned by the financial institution.

Selection-Based MFA

Some institutions require the user to answer a question from a limited set of answers, i.e. multiple-choice. Multiple questions may be returned, and the MFA answer submission must be a JSON-encoded array with answers provided in the same order as the given questions.

Auth MFA

/auth/step (POST)

MFA Credential Submit

curl -X POST https://tartan.plaid.com/auth/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d mfa="Sarah" \
  -d options='{
        "login_only":true,
        "webhook":"http://requestb.in/" }'

Question-Based MFA

http code 201
{
  "type": "questions",
  "mfa": [{"question":"What was the name of your first pet?"}],
  "access_token": "xxxxx"
}

Code-based MFA (Delivery Options)

To see a full list of code delivery options, include "list":true in the options object of the original Add Auth User call.

curl -X POST https://tartan.plaid.com/auth \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=chase \
  -d options='{"list":true}'

A successful response will include various send methods, if available.

http code 201
{
  "type": "list",
  "mfa": [
    {"mask":"t..t@plaid.com", "type":"email"},
    {"mask":"xxx-xxx-5309", "type":"phone"}
  ],
  "access_token": "xxxxx"
}

Code-based MFA (Choice Confirmation)

If there are multiple delivery options for the MFA code, you can specify if you'd like to receive the code by phone, email, etc.

curl -X POST https://tartan.plaid.com/auth/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"type":"phone"}}'

Or specify a specific phone number, email, etc. if applicable.

curl -X POST https://tartan.plaid.com/auth/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"mask":"xxx-xxx-5309"}}'

Once a delivery option has been chosen and submitted via the /step route, you will receive confirmation that the code has been sent.

http code 201
{
  "type": "device",
  "mfa": {
    "message": "Code sent to xxx-xxx-5309"
  },
  "access_token": "xxxxx"
}

The MFA code can then be submitted

curl -X POST https://tartan.plaid.com/auth/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d mfa=1234

Selection-based MFA

http code 201
{
  "type": "selections",
  "mfa": [
   {
     "question": "Did you open account 'Checking: 000' in Las Vegas?",
     "answers": [
       "Yes",
       "No"
     ]
   },
   {
     "question": "Did you open account 'Savings: 111' in Las Vegas?",
     "answers": [
       "Yes",
       "No"
     ]
   }
 ],
  "access_token": "xxxxx"
}

Selection-Based MFA Answers Submit

/auth/step (POST)
curl -X POST https://tartan.plaid.com/auth/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa='["Yes", "No"]' \
  -d access_token={ACCESS_TOKEN}

Get Auth Data

Once a user has been added to the Auth route, their account and routing information can be retrieved at any time with the user's access_token.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN returned when the user was added.

Get Auth Data

/auth/get (POST)

Get Auth Data Submit

curl -X POST https://tartan.plaid.com/auth/get \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Get Auth Data Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Update Auth User

When a user changes their password or MFA credentials with a financial institution or is locked out of their account, they must update their credentials with Plaid as well. To do so, send a PATCH request with the updated credentials. If multi-factor authentication (MFA) is required, send additional PATCH requests to the /auth/step route as needed.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
access_token required The ACCESS_TOKEN of the user you wish to update.

Update Auth User

/auth (PATCH)

Update Auth User Submit

curl -X PATCH https://tartan.plaid.com/auth \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d username=plaid_test \
  -d password=plaid_good \
  -d access_token={ACCESS_TOKEN}

Update Auth User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Update Auth User Submit (MFA)

curl -X PATCH https://tartan.plaid.com/auth/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Delete Auth User

This will remove a user from your account, as specified by a particular access_token. This process is irrevocable. You may add the user again using the Add Auth User process, but a new access_token will be generated.

To remove a user, send a request with the following parameters. These can be sent in as a query string or in the body.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN that you wish to be removed from your account.

Delete Auth User

/auth (DELETE)

Delete Auth User Submit

curl -X DELETE https://tartan.plaid.com/auth \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Delete Auth User Response

http code 200
{
   "message": "Successfully removed from your account"
}

Info

Info Overview

The Info endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses.

Add Info User

To retrieve an account holder's information, send a request with the following parameters. In certain cases, depending on the Financial Institution, you might be required to submit additional information in the credentials object such as a PIN number. For more details regarding these institution-specific requirements, check out our institutions endpoint.

Once Plaid receives this data, we will verify the credentials and return a success, failure, or MFA notification, usually under five seconds. Included in the success notification is an access_token that is required to access that users' data.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
type required The institution code that you want to access.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
options optional See Info options.
Option Type Details
list boolean default is false
If the institution requires a code-based MFA credential, this option will list the available methods. For example, Email (ex a...z@plaid.com), Text (ex 123-...-4321). See MFA for more details.

Add Info User

/info (POST)

Add Info User Submit

curl -X POST https://tartan.plaid.com/info \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d username={USERNAME} \
  -d password={PASSWORD} \
  -d type={TYPE}

Add Info User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "info": {
    "emails": [
      {
        "primary": true,
        "type": "personal",
        "data": "kelly.walters30@example.com"
      }
    ],
    "addresses": [
      {
        "primary": true,
        "data": {
          "zip": "94114",
          "state": "CA",
          "city": "San Francisco",
          "street": "3819 Greenhaven Ln"
        }
      }
    ],
    "phone_numbers": [
      {
        "primary": true,
        "type": "home",
        "data": "4673956022"
      }
    ],
    "names": [
      "Kelly Walters"
    ]
  },
  "access_token": "xxxxx"
}

Info MFA

Some banks require multi-factor authentication (MFA) and the Step route is built to submit the additional information needed. Users are first submitted via the standard Add Info User process, and the MFA data is sent through an additional request to the Step route.

Plaid is actively working to reduce the MFA requirements for users at the financial institutions we support. As such, we recommend building your integration with the expectation that MFA is always a possibility, but not always required.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
mfa required The extra information needed in the format: {mfa:'xxxxx'}.

The mfa parameter is not required when specifying a MFA send_method in the request options.
access_token required The access_token is returned when the user is added.
options optional Add these MFA options to the original options from the Add Info User request as necessary.
MFA Options Details
send_method object Default is first available email
For Code-Based MFA only, you may specify a type {"type":"phone"} or one of the returned masks {"mask":"123-...-4321"} that were returned by the initial {"list":true} submit call. For more details, see the Code-Based MFA section below.

Question-Based MFA

Question-based authentication (type=questions) requires the user to answer a security question. With some financial institutions, multiple security questions may be required. To handle multiple security questions, it is recommended that you continue to post to the route until an http code 200 is received.

Code-Based MFA

Some institutions require an MFA code that is sent to your email or phone. If there are multiple potential delivery methods, we allow you to specify which you'd like to use. To see a list of delivery options, specify {"list":true} in the options object of the original /info submit call.

After receiving the list of delivery options (as shown on the right), you may specify the delivery method by sending {"send_method":{"type":"phone"}} in the options object of your call to the /info/step endpoint. When multiple options exist for a particular send method, you may specify the phone number, email, etc. by sending in the mask. For example: {"send_method":{"mask":"xxx-xxx-1234"}}

If no delivery option is specified, Plaid will default to the first email returned by the financial institution.

Info MFA

/info/step (POST)

MFA Credential Submit

curl -X POST https://tartan.plaid.com/info/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Question-Based MFA

http code 201
{
  "type": "questions",
  "mfa": [{"question":"What was the name of your first pet?"}],
  "access_token": "xxxxx"
}

Code-based MFA (Delivery Options)

To see a full list of code delivery options, include "list":true in the options object of the original Add Info User call.

curl -X POST https://tartan.plaid.com/info \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=chase \
  -d options='{"list":true}'

A successful response will include various send methods, if available.

http code 201
{
  "type": "list",
  "mfa": [
    {"mask":"t..t@plaid.com", "type":"email"},
    {"mask":"xxx-xxx-5309", "type":"phone"}
  ],
  "access_token": "xxxxx"
}

Code-based MFA (Choice Confirmation)

If there are multiple delivery options for the MFA code, you can specify if you'd like to receive the code by phone, email, etc.

curl -X POST https://tartan.plaid.com/info/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"type":"phone"}}'

Or specify a specific phone number, email, etc. if applicable.

curl -X POST https://tartan.plaid.com/info/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"mask":"xxx-xxx-5309"}}'

Once a delivery option has been chosen and submitted via the /step route, you will receive confirmation that the code has been sent.

http code 201
{
  "type": "device",
  "mfa": {
    "message": "Code sent to xxx-xxx-5309"
  },
  "access_token": "xxxxx"
}

The MFA code can then be submitted

curl -X POST https://tartan.plaid.com/info/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d mfa=1234

Get Info Data

Once a user has been added to the Info route, the account holder information can be retrieved at any time with the user's ACCESS_TOKEN.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN returned when the user was added.

Get Info Data

/info/get (POST)

Get Info Data Submit

curl -X POST https://tartan.plaid.com/info/get \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Get Info Data Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "info": {
    "names": [
      "Bilbo Baggins"
   ],
    "emails": [
      {"data":"bilbo.baggins@plaid.com", "type":"primary"}],
    "phone_numbers": [
      {"data":"111-222-3456", "type":"work", "primary":false},
      {"data":"123-456-7891", "type":"mobile", "primary":true}],
    "addresses": [
      { "primary": true,
        "data":
          { "street": "1 Hobbit Way",
            "city": "The Shire",
            "state": "CA",
            "zip": "94108"}}]
  },
  "access_token": "xxxxx"
}

Update Info User

When a user changes their password or MFA credentials with a financial institution or is locked out of their account, they must update their credentials with Plaid as well. To do so, send a PATCH request with the updated credentials. If multi-factor authentication (MFA) is required, send additional PATCH requests to the /info/step route as needed.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
access_token required The ACCESS_TOKEN of the user you wish to update.

Update Info User

/info (PATCH)

Update Info User Submit

curl -X PATCH https://tartan.plaid.com/info \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d username=plaid_test \
  -d password=plaid_good \
  -d access_token={ACCESS_TOKEN}

Update Info User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Update Info User Submit (MFA)

curl -X PATCH https://tartan.plaid.com/info/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Delete Info User

This will remove a user from our system, as specified by a particular access_token. This process is irrevocable. You may add the user again using the Add Info User process, but a new access_token will be generated.

To remove a user, send a request with the following parameters. These can be sent in as a query string or in the body.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN that you wish to be removed from the system.

Delete Info User

/info (DELETE)

Delete Info User Submit

curl -X DELETE https://tartan.plaid.com/info \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Delete Info User Response

http code 200
{
   "message": "Successfully removed from system"
}

Income

Income Overview

The Income endpoint allows you to retrieve various information pertaining to a user's income. In addition to the annual income, detailed information will be provided for each contributing income stream (or job). Details on each of these fields can be found below.

Income data elements

Key Description
last_year_income The sum of user's income over the past 365 days. If we have less than 365 days of data this will be less than a full year's income.
last_year_income_before_tax last_year_income interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
projected_yearly_income User's income extrapolated over a year based on current, active income streams. Income streams become inactive if they have not recurred for more than two cycles. For example, if a weekly paycheck hasn't been seen for the past two weeks, it is no longer active.
projected_yearly_income_before_tax projected_yearly_income interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
income_streams An array of income streams with detailed information on each. See income streams.
max_number_of_overlapping_income_streams Max number of income streams present at the same time over the past 365 days.
number_of_income_streams Total number of distinct income streams received over the past 365 days.

Income streams

Parameter Description
active A boolean representing whether or not the income stream is active.
monthly_income The monthly income associated with the income stream.
monthly_std The standard deviation of the monthly income.
period The most common time, in days, between deposits for the income stream.
confidence A numeric representation of our confidence in the income data associated with this particular income stream, with 0 being the lowest confidence and 1 being the highest.
days Extent of data found for this income stream.
name Name of the entity associated with this income stream.

Add Income User

To retrieve a user's income information, send a request with the following parameters. In certain cases, depending on the Financial Institution, you might be required to submit additional information in the credentials object such as a PIN number. For more details regarding these institution-specific requirements, check out our institutions endpoint.

Once Plaid receives this data, we will verify the credentials and return a success, failure, or MFA notification, usually under five seconds. Included in the success notification is an access_token that is required to access that users' data.

All new user requests to /income require a webhook address that we will send a notification to once income has been calculated. Depending on the extent of data available for a given user, this webhook notification may take anywhere from 30 to 300 seconds. Once the webhook has been received, make a get income data request to retrieve the user's income information. To learn more about webhooks, check out webhook.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
type required The institution code that you want to access.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin USAA only Pin number required only for USAA accounts.
options optional See income options.
Option Type Details
webhook string *default is null
This webhook address will be hit once the user's income has been calculated. See webhook.
list boolean default is false
If the institution requires a code-based MFA credential, this option will list the available methods. For example, Email (ex a...z@plaid.com), Text (ex 123-...-4321). See MFA for more details.

Add Income User

/income (POST)

Add Income User Submit

curl -X POST https://tartan.plaid.com/income \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=wells \
  -d options='{"webhook":"http://requestb.in"}'

Add Income User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Income Webhook Response

http code 200
{
 "message": "income data available",
 "access_token": "xxxxx",
 "code": 10
}

Income MFA

Some banks require multi-factor authentication (MFA) and the Step route is built to submit the additional information needed. Users are first submitted via the standard Add Income User process, and the MFA data is sent through an additional request to the Step route.

Plaid is actively working to reduce the MFA requirements for users at the financial institutions we support. As such, we recommend building your integration with the expectation that MFA is always a possibility, but not always required.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
mfa required The extra information needed in the format: {mfa:'xxxxx'}.

The mfa parameter is not required when specifying a MFA send_method in the request options.
access_token required The access_token is returned when the user is added.
options optional Add these MFA options to the original options from the Add Income User request as necessary.
MFA Options Details
send_method object Default is first available email
For Code-Based MFA only, you may specify a type {"type":"phone"} or one of the returned masks {"mask":"123-...-4321"} that were returned by the initial {"list":true} submit call. For more details, see the Code-Based MFA section below.

Question-Based MFA

Question-based authentication (type=questions) requires the user to answer a security question. With some financial institutions, multiple security questions may be required. To handle multiple security questions, it is recommended that you continue to post to the route until an http code 200 is received.

Code-Based MFA

Some institutions require an MFA code that is sent to your email or phone. If there are multiple potential delivery methods, we allow you to specify which you'd like to use. To see a list of delivery options, specify {"list":true} in the options object of the original /income submit call.

After receiving the list of delivery options (as shown on the right), you may specify the delivery method by sending {"send_method":{"type":"phone"}} in the options object of your call to the /income/step endpoint. When multiple options exist for a particular send method, you may specify the phone number, email, etc. by sending in the mask. For example: {"send_method":{"mask":"xxx-xxx-1234"}}

If no delivery option is specified, Plaid will default to the first email returned by the financial institution.

Income MFA

/income/step (POST)

MFA Credential Submit

curl -X POST https://tartan.plaid.com/income/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Question-Based MFA

http code 201
{
  "type": "questions",
  "mfa": [{"question":"What was the name of your first pet?"}],
  "access_token": "xxxxx"
}

Code-based MFA (Delivery Options)

To see a full list of code delivery options, include "list":true in the options object of the original Add Income User call.

curl -X POST https://tartan.plaid.com/income \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=chase \
  -d options='{
       "list":true,
       "webhook":"http://requestb.in"}'

A successful response will include various send methods, if available.

http code 201
{
  "type": "list",
  "mfa": [
    {"mask":"t..t@plaid.com", "type":"email"},
    {"mask":"xxx-xxx-5309", "type":"phone"}
  ],
  "access_token": "xxxxx"
}

Code-based MFA (Choice Confirmation)

If there are multiple delivery options for the MFA code, you can specify if you'd like to receive the code by phone, email, etc.

curl -X POST https://tartan.plaid.com/income/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"type":"phone"}}'

Or specify a specific phone number, email, etc. if applicable.

curl -X POST https://tartan.plaid.com/income/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"mask":"xxx-xxx-5309"}}'

Once a delivery option has been chosen and submitted via the /step route, you will receive confirmation that the code has been sent.

http code 201
{
  "type": "device",
  "mfa": {
    "message": "Code sent to xxx-xxx-5309"
  },
  "access_token": "xxxxx"
}

The MFA code can then be submitted

curl -X POST https://tartan.plaid.com/income/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d mfa=1234

Get Income Data

Once a user has been added to the Income route, the account holder information can be retrieved at any time with the user's ACCESS_TOKEN.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN returned when the user was added.

Get Income Data

/income/get (POST)

Get Income Data Submit

curl -X POST https://tartan.plaid.com/income/get \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Get Income Data Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "income": {
    "income_streams": [
      {
        "monthly_income": 5250,
        "confidence": 1.0,
        "days": 284,
        "name": "PLAID"
      },
      {
        "monthly_income": 2400,
        "confidence": 0.95,
        "days": 415,
        "name": "BAGUETTES INC"
      }
    ],
    "last_year_income": 56000,
    "last_year_income_before_tax": 87500,
    "projected_yearly_income": 63000,
    "projected_yearly_income_before_tax": 97520,
    "max_number_of_overlapping_income_streams": 1,
    "number_of_income_streams": 2
  },
  "access_token": "xxxxx"
}

Update Income User

When a user changes their password or MFA credentials with a financial institution or is locked out of their account, they must update their credentials with Plaid as well. To do so, send a PATCH request with the updated credentials. If multi-factor authentication (MFA) is required, send additional PATCH requests to the /income/step route as needed.

PATCH may also be used to update the webhook associated with a particular user. A PATCH request submitted without credentials but with a webhook will trigger a confirmation webhook.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
access_token required The ACCESS_TOKEN of the user you wish to update.

Update Income User

/income (PATCH)

Update Income User Submit

curl -X PATCH https://tartan.plaid.com/income \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d username=plaid_test \
  -d password=plaid_good \
  -d access_token={ACCESS_TOKEN}

Update Income User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Update Income User Submit (MFA)

curl -X PATCH https://tartan.plaid.com/income/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Update Income User Webhook

curl -X PATCH https://tartan.plaid.com/income \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"webhook":"http://requestb.in"}'

Delete Income User

This will remove a user from our system, as specified by a particular access_token. This process is irrevocable. You may add the user again using the Add Income User process, but a new access_token will be generated.

To remove a user, send a request with the following parameters. These can be sent in as a query string or in the body.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN that you wish to be removed from the system.

Delete Income User

/income (DELETE)

Delete Income User Submit

curl -X DELETE https://tartan.plaid.com/income \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Delete Income User Response

http code 200
{
   "message": "Successfully removed from system"
}

Risk (beta)

Risk Overview

The Risk endpoint allows you to retrieve various information pertaining to a user's calculated risk. Risk profiles are generated for each underlying account and include an overall score, a breakdown of the score by various contributing parameters, and the extent of data available for analysis.

Plaid’s risk algorithm detects abnormal behavior by comparing new bank accounts to an internal database. While directly detecting risky behavior is challenging, we use our large dataset to identify normal patterns. Once an account is found to deviate from our definition of normal in our carefully chosen parameter space it is flagged as abnormal.

Risk profile data elements

Key Description
score Comprehensive risk score associated with the account, where 0 is the lowest risk and 1 is the highest.
reason A list of reasons and associated subscores contributing to the overall risk score. See reasons for a brief description of each. Detailed information can be found here.
Reason Description
transaction_amounts How transaction amounts are distributed across different buckets.
ratio_high_average Ratio of highest transaction amount to average positive transaction amount.
ratio_low_average Ratio of lowest negative transaction amount to average negative transaction amount.
high_risk_class_txns Number of transactions that fall into four specific high risk categories.
fraction_bank_fees Proportion of transactions that are bank fees.
foreign_fees Number of foreign fees per month.
bank_transfers Proportion of transactions that are transfers.
benfords_law How much transaction amounts deviate from the distribution of digits predicted by Benford's Law.
additional_risk_class_txns Number of transactions with additional risk factors.
mean_payment_amount Average credit card payment amount.
mean_payment_time Average time between credit payments.
home_state_percentage Percentage of time spent in primary spending state.
n_txns_per_month The average number of transactions this account has per month.
zero_count_credit_payments Zero count from the right for credit card payments.
zero_count Zero count from the right for all payments.

Add Risk User

To retrieve a user's risk information, send a request with the following parameters. In certain cases, depending on the Financial Institution, you might be required to submit additional information in the credentials object such as a PIN number. For more details regarding these institution-specific requirements, view the credentials link below or check out our institutions endpoint.

Once Plaid receives this data, we will verify the credentials and return a success, failure, or MFA notification, usually under five seconds. Included in the success notification is an access_token that is required to access that users' data.

All new user requests to /risk require a webhook address that we will send a notification to once risk values have been calculated. Depending on the extent of data available for a given user, this webhook notification may take anywhere from 30 to 300 seconds. Once the webhook has been received, make a get risk data request to retrieve the user's risk information. To learn more about webhooks, check out webhook.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
type required The institution code that you want to access.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin USAA only Pin number required only for USAA accounts.
options optional See risk options.
Option Type Details
webhook string *default is null
This webhook address will be hit once the user's risk has been calculated. See webhook.
list boolean default is false
If the institution requires a code-based MFA credential, this option will list the available methods. For example, Email (ex a...z@plaid.com), Text (ex 123-...-4321). See MFA for more details.

Add Risk User

/risk (POST)

Add Risk User Submit

curl -X POST https://tartan.plaid.com/risk \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=wells \
  -d options='{"webhook":"http://requestb.in"}'

Add Risk User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Risk Webhook Response

http code 200
{
 "message": "risk data available",
 "access_token": "xxxxx",
 "code": 20
}

Risk MFA

Some banks require multi-factor authentication (MFA) and the Step route is built to submit the additional information needed. Users are first submitted via the standard Add Risk User process, and the MFA data is sent through an additional request to the Step route.

Plaid is actively working to reduce the MFA requirements for users at the financial institutions we support. As such, we recommend building your integration with the expectation that MFA is always a possibility, but not always required.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
mfa required The extra information needed in the format: {mfa:'xxxxx'}.

The mfa parameter is not required when specifying a MFA send_method in the request options.
access_token required The access_token is returned when the user is added.
options optional Add these MFA options to the original options from the Add Risk User request as necessary.
MFA Options Details
send_method object Default is first available email
For Code-Based MFA only, you may specify a type {"type":"phone"} or one of the returned masks {"mask":"123-...-4321"} that were returned by the initial {"list":true} submit call. For more details, see the Code-Based MFA section below.

Question-Based MFA

Question-based authentication (type=questions) requires the user to answer a security question. With some financial institutions, multiple security questions may be required. To handle multiple security questions, it is recommended that you continue to post to the route until an http code 200 is received.

Code-Based MFA

Some institutions require an MFA code that is sent to your email or phone. If there are multiple potential delivery methods, we allow you to specify which you'd like to use. To see a list of delivery options, specify {"list":true} in the options object of the original /risk submit call.

After receiving the list of delivery options (as shown on the right), you may specify the delivery method by sending {"send_method":{"type":"phone"}} in the options object of your call to the /risk/step endpoint. When multiple options exist for a particular send method, you may specify the phone number, email, etc. by sending in the mask. For example: {"send_method":{"mask":"xxx-xxx-1234"}}

If no delivery option is specified, Plaid will default to the first email returned by the financial institution.

Risk MFA

/risk/step (POST)

MFA Credential Submit

curl -X POST https://tartan.plaid.com/risk/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Question-Based MFA

http code 201
{
  "type": "questions",
  "mfa": [{"question":"What was the name of your first pet?"}],
  "access_token": "xxxxx"
}

Code-based MFA (Delivery Options)

To see a full list of code delivery options, include "list":true in the options object of the original Add Risk User call.

curl -X POST https://tartan.plaid.com/risk \
  -d client_id=test_id \
  -d secret=test_secret \
  -d username=plaid_test \
  -d password=plaid_good \
  -d type=chase \
  -d options='{"list":true, "webhook":"http://requestb.in"}'

A successful response will include various send methods, if available.

http code 201
{
  "type": "list",
  "mfa": [
    {"mask":"t..t@plaid.com", "type":"email"},
    {"mask":"xxx-xxx-5309", "type":"phone"}
  ],
  "access_token": "xxxxx"
}

Code-based MFA (Choice Confirmation)

If there are multiple delivery options for the MFA code, you can specify if you'd like to receive the code by phone, email, etc.

curl -X POST https://tartan.plaid.com/risk/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"type":"phone"}}'

Or specify a specific phone number, email, etc. if applicable.

curl -X POST https://tartan.plaid.com/risk/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"send_method":{"mask":"xxx-xxx-5309"}}'

Once a delivery option has been chosen and submitted via the /step route, you will receive confirmation that the code has been sent.

http code 201
{
  "type": "device",
  "mfa": {
    "message": "Code sent to xxx-xxx-5309"
  },
  "access_token": "xxxxx"
}

The MFA code can then be submitted

curl -X POST https://tartan.plaid.com/risk/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d mfa=1234

Get Risk Data

Once a user has been added to the Risk route, the account holder information can be retrieved at any time with the user's ACCESS_TOKEN.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN returned when the user was added.

Get Risk Data

/risk/get (POST)

Get Risk Data Submit

curl -X POST https://tartan.plaid.com/risk/get \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Get Risk Data Response

http code 200
{
  "accounts": [
    {
      "_id": "mjj9jp92z2fD1mLlpQYZI1gAd4q4LwTKmBNLz",
      "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
      "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
      "balance": {
        "available": 1203.42,
        "current": 1274.93
      },
      "meta": {
        "name": "Plaid Savings",
        "number": "9606"
      },
      "institution_type": "fake_institution",
      "type": "depository",
      "risk": {
        "reason": {
          "zero_count": 0.38,
          "ratio_low_average": 0.75,
          "high_risk_class_txns": 0.73,
          "bank_transfers": 0.4,
          "benfords_law": 0.65,
          "transaction_amounts": 0.78,
          "additional_risk_class_txns": 0.94,
          "foreign_fees": 0.96,
          "fraction_bank_fees": 0.64
        },
        "score": 0.79
      },
    },
  ...],
  "access_token": "xxxxx"
}

Update Risk User

When a user changes their password or MFA credentials with a financial institution or is locked out of their account, they must update their credentials with Plaid as well. To do so, send a PATCH request with the updated credentials. If multi-factor authentication (MFA) is required, send additional PATCH requests to the /risk/step route as needed.

PATCH may also be used to update the webhook associated with a particular user. A PATCH request submitted without credentials but with a webhook will trigger a confirmation webhook.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
username required Username associated with the user's financial institution.
password required Password associated with the user's financial institution.
pin usaa only Pin number associated with the user's financial institution.
access_token required The ACCESS_TOKEN of the user you wish to update.

Update Risk User

/risk (PATCH)

Update Risk User Submit

curl -X PATCH https://tartan.plaid.com/risk \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d username=plaid_test \
  -d password=plaid_good \
  -d access_token={ACCESS_TOKEN}

Update Risk User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Update Risk User Submit (MFA)

curl -X PATCH https://tartan.plaid.com/risk/step \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d mfa="Sarah" \
  -d access_token={ACCESS_TOKEN}

Update Risk User Webhook

curl -X PATCH https://tartan.plaid.com/risk \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d options='{"webhook":"http://requestb.in"}'

Delete Risk User

This will remove a user from our system, as specified by a particular access_token. This process is irrevocable. You may add the user again using the Add Risk User process, but a new access_token will be generated.

To remove a user, send a request with the following parameters. These can be sent in as a query string or in the body.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN that you wish to be removed from the system.

Delete Risk User

/risk (DELETE)

Delete Risk User Submit

curl -X DELETE https://tartan.plaid.com/risk \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Delete Risk User Response

http code 200
{
   "message": "Successfully removed from system"
}

Risk Reference

Listed below are detailed descriptions of each of the reasons contributing to the overall risk profile and score returned.

Transaction Amount

How much money is flowing through an account is an important factor in quantifying account behavior. This parameter captures how transactions amounts are distributed.

Key Description
transaction_amounts How transaction amounts are distributed across different buckets.

Ratio of Highest Amount to Average Amount

The ratio of the highest transaction amount to the average transaction amount is an indicator of large, anomalous transactions. The ratio of the lowest negative transaction amount to the average negative transaction amount is a similar indicator for negative amounts. Like the transaction amount parameter, they are important in identifying anomalous accounts because they these ratios help to quantify how an account is being used.

Key Description
ratio_high_average Ratio of highest transaction amount to average positive transaction amount.
ratio_low_average Ratio of lowest negative transaction amount to average negative transaction amount.

Transaction Classes Indicative of High Risk

The average number of overdraft, fraud, late fee and cash advance transactions per month. This parameter is helpful in detecting anomalous accounts because most normal accounts have a low number of transactions in these classes.

Key Description
high_risk_class_txns Number of transactions that fall into four specific high risk categories.

Bank Fees

The proportion of an account’s transactions that have the category “Bank Fees”. This parameter is helpful in detecting anomalous accounts because most normal accounts have a low number of transactions with this category.

Key Description
fraction_bank_fees Proportion of transactions that are bank fees.

Foreign Fees

The average number of an account’s transactions that have the subcategory “Foreign Transaction” per month. This parameter is helpful in detecting anomalous accounts because most normal accounts exhibit a relatively low number of transactions from a different country.

Key Description
foreign_fees Number of foreign fees per month.

Bank Transfers

The proportion of an account’s transactions that have the category “Transfer”. This parameter is helpful in detecting anomalous accounts because the number of transfers into and out of an account is highly correlated with abnormal behavior.

Key Description
bank_transfers Proportion of transactions that are transfers.

Benford's Law

How closely the distributions of amounts in this account follow Bendford’s Law, which describes the frequency distribution of the leading digit of each transaction amount. Financial data in normal accounts tends to follow a distribution where smaller numbers are more likely to be leading digits than larger ones. This type of analysis is well studied in detecting financial fraud. This parameter is helpful in detecting anomalous accounts because it gives an overall picture of how well an account’s amounts follow Benford’s Law.

Key Description
benfords_law How much transaction amounts deviate from the distribution of digits predicted by Benford's Law.

Additional Transaction Level Risk Factors

The average number of a combination of different risk factors that are extracted from each transaction’s name per month. This parameter is helpful in detecting anomalous accounts because most normal accounts have a low number of transactions in this class.

Key Description
additional_risk_class_txns Number of transactions with additional risk factors.

Credit Card Payment Parameters

The amount and frequency of credit card payments. These parameters are helpful in detecting anomalous accounts because most normal accounts follow a similar payment amount and time schedule.

Key Description
mean_payment_amount Average credit card payment amount.
mean_payment_time Average time between credit payments.

Location Factors

Analyzing transactional information, this is the percentage of time the user spent in their primary spending state.

Key Description
home_state_percentage Percentage of time spent in primary spending state.

Number of Transactions Per Month

The number of transactions this account has per month. This parameter is helpful in detecting anomalous accounts because it is a strong indication of how an account is being used.

Key Description
n_txns_per_month The average number of transactions this account has per month.

Zero Counter

Number of successive zeros in a transaction amount, starting from the right. This zero counter is useful in identifying deliberate manual payments, which tend to occur in clean amounts that end in 0’s. These parameters are helpful in detecting anomalous accounts because they are a strong indication of how an account is being used.

Key Description
zero_count_credit_payments Zero count from the right for credit card payments.
zero_count Zero count from the right for all payments.

Balance

Get Balance

The balance endpoint returns the real-time balance of a user's accounts. It may be used for existing users that were added via any of Plaid's products. The Current Balance is the total amount of funds in the account. The Available Balance is the Current Balance less any outstanding holds or debits that have not yet posted to the account. Note that not all institutions calculate the Available Balance. In the case that Available Balance is unavailable from the institution, Plaid will either return an Available Balance value of null or only return a Current Balance.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN of the user whose account you wish to query.

Get Balance

/balance (POST or GET)

Get Balance Submit

curl -X POST https://tartan.plaid.com/balance \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN}

Get Balance Response

http code 200
{
  "accounts": [
    {
      "_id": "mjj9jp92z2fD1mLlpQYZI1gAd4q4LwTKmBNLz",
      "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
      "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
      "balance": {
        "available": 1203.42,
        "current": 1274.93
      },
      "meta": {
        "name": "Plaid Savings",
        "number": "9606"
      },
      "institution_type": "fake_institution",
      "type": "depository"
    },
  ...],
  "access_token": "xxxxx"
}

Upgrade

Upgrade User

For an existing user that has been added via any of Plaid's products (Connect, Auth, Income, Info, or Risk), you can upgrade that user to have functionality with other products. To upgrade a user - as specified by their ACCESS_TOKEN - send a request with the following parameters.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
access_token required The ACCESS_TOKEN of the user whose account you wish to query.
upgrade_to required The product to add for the user: auth, connect, income, info, or risk.

*Note: The login:true parameter is forced and using a webhook is highly recommended. If you know that a user will use both Auth and Connect, the easiest flow to avoid additional MFA is to add the user on Auth first.

Upgrade

/upgrade (POST)

Upgrade User Submit

curl -X POST https://tartan.plaid.com/upgrade \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d access_token={ACCESS_TOKEN} \
  -d upgrade_to="connect" \
  -d options='{"webhook":"http://requestb.in/"}'

Upgrade User Response

http code 200
{
  "accounts": [
    {object},
    {object}
  ],
  "transactions": [
    {object},
    {object},
    {object}
  ],
  "access_token": "xxxxx"
}

Institutions

Institution Overview

Plaid supports thousands of financial institutions and we're always working to add support for more. The /institutions/all/search endpoint makes it easy to stay up-to-date with supported institutions and help your users find the institution they're looking for quickly.

You can also use the /institutions/all endpoint to retrieve a complete list of supported institutions. This data does change frequently and we recommend against storing it on your system. If you do store it, be sure to update it regularly.

Institutions by product

Below is product coverage information for some of our most popular institutions:

auth Auth connect Connect balance Balance info Info income Income risk Risk
amex
bbt
bofa
capone
chase
citi
nfcu
pnc
suntrust
td
us
usaa
wells

Information about transaction data availability each of these financial institutions can be found at our Help center.

To see a full list of supported institutions across all products, use the /institutions/all and /institutions/all/search endpoints documented below.

Note: While we do our best to streamline the majority of bank interactions, it's worth noting a few rare inconsistencies with certain banks and account types. For example, some newly opened accounts may be missing certain information for a short period of time while the data propagates through the bank's systems. A detailed list of such exceptions can be found below.

Institutions

/institutions/all/search (GET)
/institutions/all (POST)
/institutions/all/:id (GET)

Returns a JSON response containing details for all institutions that match the query parameters.

Parameter Type Details
q string A search query to match against the full list of institutions. Partial matches are returned making this useful for autocompletion purposes.
p string Value indicating the Plaid product to filter results by. Only valid when combined with the q option. If omitted, results are not filtered by product.
id string The id of a single institution for lookup. If this option is specified, q and p are ignored.
/institutions/all/search

Search by Bank and Product

curl -G https://tartan.plaid.com/institutions/all/search \
  -d q=redwood \
  -d p=auth

All Institutions

Returns a JSON response containing details on all financial institutions currently supported by Plaid. Due to the large number of supported institutions, results are paginated.

Use the count and offset query parameters to retrieve the desired institution data. The optional products parameter allows you to filter the list of institutions based on support for a particular product or set of products.

Parameter Type Details
client_id required CLIENT_ID provided on signup.
secret required SECRET provided on signup.
products [String] Filter only institutions with support for the product(s) specified.
Valid products are: connect, auth, info, income, and risk.
count integer The number of results to retrieve. Default is 50.
offset integer An integer number of results to skip forward from the beginning of the list. Default is 0.

All Institutions

curl -X POST https://tartan.plaid.com/institutions/all \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d count=50 \
  -d offset=0

Institutions supporting Connect

# Fetch 250 institutions that support Connect
curl -X POST https://tartan.plaid.com/institutions/all \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d products='["connect"]' \
  -d count=250 \
  -d offset=0

Institutions supporting both Auth and Info

# Fetch 50 institutions that support both Auth and Info
curl -X POST https://tartan.plaid.com/institutions/all \
  -d client_id={CLIENT_ID} \
  -d secret={SECRET} \
  -d products='["auth", "info"]' \
  -d count=50 \
  -d offset=0

Institutions by ID

Returns a JSON response containing details on a specified Financial Institution currently supported by Plaid.

Institutions by ID

curl https://tartan.plaid.com/institutions/all/ins_100000

Institutions by ID Response

http code 200
{
  "credentials": {
    "username": "User ID",
    "password": "Password"
  },
  "has_mfa": true,
  "id": "ins_100000",
  "mfa": [
    "code",
    "list",
    "questions",
    "selections"
  ],
  "name": "Union Bank",
  "products": [
    "auth",
    "balance",
    "connect",
    "income",
    "info"
  ],
  "type": "ins_100000"
}

Categories

Category Overview

Send a request to the /categories route to get detailed information on categories returned by Plaid. This endpoint requires no authentication. For a full view of Plaid categories, see the reference page.

Category

/categories (GET)
/categories/:id (GET)

All Categories

Returns a JSON response containing all Plaid categories.

All Categories

curl https://tartan.plaid.com/categories

Categories by ID

Use this endpoint to access a Plaid Category by id. The reference page contains a list of all Plaid Categories.

Categories by ID

curl https://tartan.plaid.com/categories/17001013

Category ID Response

{
  "type": "place",
  "hierarchy": [
    "Recreation",
    "Arts & Entertainment",
    "Circuses and Carnivals"
  ],
  "id": "17001013"
}