api 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 Plaid API is architected around REST, using 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 drop us a line at support@plaid.com.

Resource URL Patterns

/connect /auth /balance /upgrade /institutions /categories

gaining access

To gain access to the Plaid API, please create an account on our website. 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": {
        "limit": 12500,
        "number": "3002",
        "name": "Plaid Credit Card"
      },
      "type": "credit"
    },
...],
  "transactions": [
    {
      "_account": "YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo",
      "_id": "600r0LrVvViXjq96lBpdtyOWboBvzmsaZoeaVz",
      "amount": 12.74,
      "date": "2014-05-12",
      "name": "Golden Crepes",
      "meta": {
        "location": {
          "coordinates": {
            "lat": 40.740352,
            "lon": -74.001761
          },
          "state": "NY",
          "city": "New York",
          "address": "262 W 15th St"
        }
      },
      "pending": false,
      "score": {
        "master": 1,
        "detail": {
          "address": 1,
          "city": 1,
          "name": 1,
          "state": 1
        }
      },
      "type": {
        "primary": "place"
      },
      "category": [
        "Food and Drink",
        "Restaurants"
      ],
      "category_id": "13005000"
    },
...],
  "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 Value 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_chase...)

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 respond to success, 40X codes are for client-related failures, and 50X codes are for Plaid-related issues. We're doing our best to maximize the former and diminish the latter; however, if you find consistent issues, please contact support immediately. For a full list of response codes, see response code detail below or visit our GitHub support page.

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."
}

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 Value 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 Value 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, or Special.
amount: The settled dollar value. Positive values when money moves out of the account; negative values when money moves in.
date: The date that the transaction was posted by the financial institution (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.
_pendingTransaction: The id of a posted transaction's associated pending transcation - where applicable.

Example Account Data

"accounts": [
  {
    "_id": "YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo",
    "_item": "aWWVW4VqGqIdaP495QyOSVLN1nzjLwhXaPDJJ",
    "_user": "bkkVkMVwQwfYmBMy9jzqHQob9O1KwpFaEyLOE",
    "balance": {
      "available": 9930,
      "current": 2275.58
    },
    "institution_type": "fake_institution",
    "meta": {
      "limit": 12500,
      "number": "3002",
      "name": "Plaid Credit Card"
    },
    "type": "credit"
  },
...]

Example Transaction Data

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

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.

Transactional data is retrieved from the same /connect endpoint used to authenticate users. 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 transactional data POST: /connect/get

add user

To add a new end-user, submit their institution type, credentials, and email address 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 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 associated with the user's financial institution.
options: optional See submit options.

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 User

/connect (POST)

Add 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 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 occured. 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 response

Initial Transaction Webhook
http code 200
{
 "message": "Initial transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 0
}
Historical Transaction Webhook
http code 200
{
 "message": "Historical transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 1
}
Normal Transaction Webhook
http code 200
{
 "message": "Normal transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 2
}
Removed Transaction Webhook
http code 200
{
 "message": "Transactions removed",
 "access_token": "xxxxx",
 "removed_transactions": ["53dff5c470ae103f1c1c3523", "53dff5cb70ae103f1c1c3524"],
 "code": 3
}
User's Webhook Updated
http code 200
{
 "message": "Webhook acknowledged",
 "access_token": "xxxxx",
 "code": 4
}
Error Response Webhook Example
http code 402
{
 "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.

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"
}

mfa authentication

Some banks may 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 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'}.
access_token: required The ACCESS_TOKEN returned when the user was added.
options: optional See MFA options.

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.

Multi-Factor Authentication

/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 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"},
    {"mask":"SafePass Card", "type":"card"}
  ],
  "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"
}

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

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

Retrieve Transactions

/connect/get (POST)

Retrieve Transactions Submit

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

Retrieve Transactions Response

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

update user

When a user changes their username, 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 User

/connect (PATCH)

Update 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 User Response

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

Update User Submit (MFA)

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

Update 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 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 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 User

/connect (DELETE)

Delete User Submit

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

Delete User Response

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

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. Access to this method is restricted and you must have an approved client ID. 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 associated with the user's financial institution.
options: optional See auth options.

New User

/auth (POST)

New 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

Auth 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"
}

mfa auth

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 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'}.
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 User request as necessary.

Note: The login_only: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 Auth first.

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.

MFA Auth

/auth/step (POST)

MFA Credential Submission

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 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"},
    {"mask":"SafePass Card", "type":"card"}
  ],
  "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"
}

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}

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

Retrieve Data

/auth/get (POST)

Retrieve Data Submit

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

Retrieve Data Response

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

update auth user

When a user changes their username, 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.

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 User

/auth (PATCH)

Update 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 User Response

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

Update User Submit (MFA)

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

Update User Webhook

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

delete auth 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 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 the system.

Delete User

/auth (DELETE)

Delete User Submit

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

Delete User Response

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

balance

retrieve 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 (Connect or Auth). 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.

Check Balance

/balance (POST or GET)

Check Balance Submit

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

Check 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 or Auth), 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.

Before using the /upgrade route, make sure that it is enabled for your account. To learn more or enable your account for use with /upgrade, please drop us a line.

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

*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 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 Response

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

institutions

institution overview

Send a request to the /institution route to get detailed information on the Financial Institutions currently supported by Plaid. This endpoint requires no authentication.

Institution Type Notes
American Express: {type: amex} No MFA
Bank of America: {type: bofa} Question-based MFA (3 questions) or code-based MFA (SafePass)
Capital One 360: {type: capone360} Question-based MFA (1 to 3 questions)
Charles Schwab: {type: schwab} No MFA
Chase: {type: chase} Code-based MFA
Citi: {type: citi} Question-based MFA and selection-based MFA (Auth only)
Fidelity: {type: fidelity} No MFA
PNC: {type: pnc} Question-based MFA (3 questions)
Silicon Valley Bank (in Beta): {type: svb} No MFA
US Bank: {type: us} Question-based MFA (1 to 3 questions)
USAA: {type: usaa} Question-based MFA (3 questions)
Wells Fargo: {type: wells} No MFA

Additional information regarding the historical data available for each financial institution can be found on our support channel here.

*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 (GET) /institutions/:id (GET)

all institutions

Returns a JSON response containing details on all Financial Institutions currently supported by Plaid.

All Institutions

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

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/5301a93ac140de84910000e0

Institutions by ID Response

http code 200
{
  "id": "5301a93ac140de84910000e0",
  "name": "Bank of America",
  "type": "bofa",
  "has_mfa": true,
  "mfa": [
    "code",
    "list",
    "questions"
  ]
}

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"
}

resources

libraries

All libraries for Plaid are available via our GitHub account. These libraries are a work in progress—please feel free to submit pull requests or issues directly via GitHub. If you've built anything that you'd be willing to share, please let us know and we'll link to it here (and send you a t-shirt)!

Libraries

Go: plaid-go Node: plaid-node Python: plaid-python

Community Libraries

Ruby: plaid-ruby Java: plaid-java PHP: plaid-backend CakePHP: cakephp-plaid CLI: plaid-cli

support

Please file support questions and feature requests in our GitHub channel. This channel is monitored regularly, and is generally the fastest way to get in touch with our engineering team. Suggested edits or updates to the documentation should also be addressed here. For emergencies or client-specific issues, you can also reach us at support@plaid.com. We value a public forum for bugs, fixes, and general questions—so please use this option sparingly.

Contact Support

GitHub: Plaid Support Urgent Questions: support@plaid.com

Community Resources

Stack Overflow: Plaid-Tag Quora: Plaid-Company