API Host

https://sandbox.plaid.com (Sandbox)
https://development.plaid.com (Development)
https://production.plaid.com (Production)

The Sandbox environment is unrestricted and supports only test Items. The Development environment supports up to 100 live Items. All testing should be done in our Sandbox and Development environments. All requests to Production will be billed. When you’re getting ready to launch into Production, please request Production API access via the Dashboard.

Product access endpoints:

/auth/get
/transactions/get
/income/get
/identity/get
/accounts/balance/get

Link endpoints:

/item/public_token/exchange
/item/public_token/create

Item management:

/accounts/get
/item/get
/item/webhook/update
/item/access_token/invalidate
/item/access_token/update_version
/item/delete

Institutions endpoints:

/institutions/get
/institutions/get_by_id
/institutions/search

Categories endpoints:

/categories/get

Example Item

{
 "access_token": "access-sandbox-e9317406-8413-43c6",
 "item": {
   "available_products": [
     "balance",
     "auth"
   ],
   "billed_products": [
     "identity",
     "transactions"
   ],
   "error": null,
   "institution_id": "ins_109508",
   "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
   "webhook": "https://plaid.com/example/hook"
 },
 "request_id": "qpCtl"
}

Client-side Link integration

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

<button id="link-button">Open Link</button>

<script>
var linkHandler = Plaid.create({
 env: 'sandbox',
 clientName: 'Plaid Sandbox',
 // Replace '<PUBLIC_KEY>' with your own `public_key`
 key: '<PUBLIC_KEY>',
 product: ['auth'],
 // Use webhooks to get transaction and error updates
 webhook: '<WEBHOOK_URL>',
 onSuccess: function(public_token, metadata) {
   // Send the public_token to your app server here.
   // The metadata object contains info about the
   // institution the user selected and the
   // account_id, if selectAccount is enabled.
 },
 onExit: function(err, metadata) {
   // The user exited the Link flow.
   if (err != null) {
     // The user encountered a Plaid API error
     // prior to exiting.
   }
   // metadata contains information about the
   // institution that the user selected and the
   // most recent API request IDs. Storing this
   // information can be helpful for support.
 }
});
// Trigger the standard institution select view
document.getElementById('link-button').onclick = function() {
 linkHandler.open();
};
</script>

Server-side Link handler

var express = require('express');
var plaid = require('plaid');

var app = express();

var plaidClient = new plaid.Client(process.env.PLAID_CLIENT_ID,
process.env.PLAID_SECRET,
process.env.PUBLIC_KEY,
plaid.environments.sandbox);
app.post('/authenticate', function(req, res) {
 var public_token = req.body.public_token;
 // Exchange a public_token for a Plaid access_token
 plaidClient.exchangePublicToken(public_token,
 function(err, exchangeTokenRes) {
   if (err != null) {
     // Handle error!
   } else {
     // The access_token can be used to make API calls to
     // retrieve product data - store access_token and item_id
     // in a persistent datastore
     var access_token = exchangeTokenRes.access_token;
     plaidClient.getAuth(access_token, function(err, authRes) {
       if (err != null) {
         // Handle error!
       } else {
         // An array of accounts for this Item, containing
         // high-level account information and account numbers
         // for checkings and savings accounts
         res.json({
          accounts: authRes.accounts,
          numbers: authRes.numbers
         });
       }
     });
   }
 });
});

Link Institution schema

{
 name: 'Citi',
 institution_id: 'ins_5',
 auth: true,
 transactions: true
}

Metadata schema

{
 "link_session_id": String,
 "institution": {
   "name": String,
   "institution_id": String
 },
 "account": {
   "id": String
   "name": String
 }
}

Error Object schema

{
 "display_message": String,
 "error_code": String,
 "error_message": String
 "error_type": String,
}

Metadata schema

{
 "link_session_id": String,
 "institution": {
   "name": String,
   "institution_id": String
 },
 "request_id": String,
 "status": String,
}

Open to the Select Institution view

Open Link to the Select Institution view Link will handle the whole flow for connecting your users' bank

// Configure link
var linkHandler = Plaid.create(...)

// Open Link
linkHandler.open()

Open to the Custom Bank view

// Configure link
var linkHandler = Plaid.create(...)

// Pull the latest list of Plaid institutions
var institutionID = 'ins_1';

// Open Link with the institution code
linkHandler.open(institutionID)

.exit() example

// Initialize Link
var linkHandler = Plaid.create(...)

// Force exit - Link exits immediately
linkHandler.exit({ force: true })

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
linkHandler.exit()

// This is equivalent to the above:
linkHandler.exit({ force: false })

Exchange Token

POST /item/public_token/exchange

Exchange token request

curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "public_token": "public-sandbox-fb7cca4a-82e6-4707"
 }'

plaidClient.exchangePublicToken(public_token, function(err, apiResponse) {
 var accessToken = apiResponse.access_token;
 var itemId = apiResponse.item_id;
});

response = client.item.public_token.exchange(public_token)
access_token = response['access_token']
item_id = response['item_id']

response = client.Item.public_token.exchange(public_token)
access_token = response['access_token']
item_id = response['item_id']

Response<ItemPublicTokenExchangeResponse> response =
 client()
 .service()
 .itemPublicTokenExchange(new ItemPublicTokenExchangeRequest(publicToken))
 .execute();
String accessToken = response.body().getAccessToken();

Exchange Token response

http code 200
{
 "access_token": "access-sandbox-7c69d345-fd46-461f",
 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
 "request_id": "Aim3b"
}

Create Public Token

POST /item/public_token/create

Create Public Token request

curl -X POST https://sandbox.plaid.com/item/public_token/create \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": access-sandbox-7c69d345-fd46-461f"
 }'

# create a public_token for use with Plaid Link's update mode
response = client.item.public_token.create(access_token)
# use the generated public_token to initialize Plaid Link in update
# mode for a user's Item so that they can provide updated credentials
# or MFA information
public_token = response['public_token']

# create a public_token for use with Plaid Link's update mode
create_response = client.Item.public_token.create(access_token)
# use the generated public_token to initialize Plaid Link in update
# mode for a user's Item so that they can provide updated credentials
# or MFA information
public_token = response['public_token']

// Create a public_token for use with Plaid Link's update mode
client.createPublicToken(ACCESS_TOKEN, (err, result) => {
 // Handle err
 // Use the generated public_token to initialize Plaid Link in update
 // mode for a user's Item so that they can provide updated credentials
 // or MFA information
 const publicToken = result.public_token;
});

// Create a public_token for use with Plaid Link's update mode
Response<ItemPublicTokenCreateResponse> response =
 client().service().itemPublicTokenCreate(
  new ItemPublicTokenCreateRequest("ACCESS_TOKEN")).execute();
String publicToken;
if (response.isSuccessful()) {
 // Use the generated public_token to initialize Plaid Link in update
 // mode for a user's Item so that they can provide updated credentials
 // or MFA information
 publicToken = response.body().getPublicToken();
}

Create Public Token response

http code 200
{
 "public_token": "public-sandbox-fb7cca4a-82e6-4707",
 "request_id": "Aim3b"
}

Initialize Link in update mode

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script>
// Initialize Link with the `token` parameter
// set to the generate public_token for the Item
var linkHandler = Plaid.create({
 env: 'sandbox',
 clientName: 'Client Name',
 key: '<PUBLIC_KEY>',
 products: ['auth', 'transactions'],
 token: '<GENERATED_PUBLIC_TOKEN>',
 onSuccess: function(public_token, metadata) {
   // You do not need to repeat the /item/public_token/exchange
   // process when a user uses Link in update mode.
   // The Item's access_token has not changed.
 },
 onExit: function(err, metadata) {
   // The user exited the Link flow.
   if (err != null) {
     // The user encountered a Plaid API error prior
     // to exiting.
   }
   // metadata contains information about the institution
   // that the user selected and the most recent API request
   // IDs. Storing this information is helpful for support.
 },
});
// Trigger the authentication view
document.getElementById('linkButton').onclick = function() {
 // Link will automatically detect the institution ID
 // associated with the public token and present the
 // credential pane to your user.
 linkHandler.open();
};
</script>

Link WebView initialization URL

https://cdn.plaid.com/link/v2/stable/link.html
 ?isWebview=true
 &key=[PUBLIC_KEY]
 &env=sandbox
 &product=transactions,auth
 &selectAccount=true
 &clientName=Plaid%20Demo

Using Custom Initializers with a WebView

https://cdn.plaid.com/link/v2/stable/link.html
 ?isWebview=true
 &key=[PUBLIC_KEY]
 ...
 &institution=ins_100101

Initialize Link in update mode with a public token

https://cdn.plaid.com/link/v2/stable/link.html
 ?isWebview=true
 &key=[PUBLIC_KEY]
 ...
 &token=[GENERATED_PUBLIC_TOKEN]

Link WebView connected event

plaidlink://connected
 ?public_token=public-sandbox-fb7cca4a-82e6-4707
 &account_id=QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK
 &account_name=Plaid%20Savings
 &institution_id=ins_3
 &institution_name=Chase

Link WebView exit event

plaidlink://exit
 ?status=requires_credentials
 &error_code=ITEM_LOGIN_REQUIRED
 &error_display_message=The%20provided%20credentials%20were%20not%20correct.%20Please%20try%20again.
 &error_message=the%20provided%20credentials%20were%20not%20correct
 &error_type=ITEM_ERROR
 &institution_id=ins_3
 &institution_name=Chase
 &request_id=2ZPIa

Retrieve Auth

POST /auth/get

Retrieve Auth Request

curl -X POST https://sandbox.plaid.com/auth/get \
-H 'content-type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_token": String
}'

# Use Auth and pull account and routing numbers for an Item
response = @client.Auth.get(@access_token)
numbers = response['numbers']

# Use Auth and pull account and routing numbers for an Item
response = client.Auth.get(access_token)
numbers = response['numbers']

// Use Auth and pull account and routing numbers for an Item
client.getAuth(accessToken, {}, (err, results) => {
 // Handle err
 // Pull account and routing numbers for depository accounts
 const accountData = results.accounts;
 const accountAndRoutingNumbers = results.numbers;
});

// Use Auth and pull account and routing numbers for an Item
Response<AuthGetResponse> response =
 client().service().authGet(new AuthGetRequest("ACCESS_TOKEN")).execute();
for (AuthGetResponse.Numbers auth : response.body().getAuth()) { ... }

Retrieve Auth Response

http code 200
{
 "accounts": [{
   "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
   "balances": {
     "available": 100,
     "current": 110,
     "limit": null
   },
   "mask": "0000",
   "name": "Plaid Checking",
   "official_name": "Plaid Gold Checking",
   "subtype": "checking",
   "type": "depository"
 }],
 "numbers": [{
   "account": "1111222233330000",
   "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
   "routing": "011401533",
   "wire_routing": "021000021"
  }],
 "item": {Object},
 "request_id": "45QSn"
}

Retrieve Accounts

POST /accounts/get

Retrieve Accounts Request

curl -X POST https://sandbox.plaid.com/accounts/get \
-H 'content-type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_token": String
}'

# Pull the accounts associated with the Item
response = @client.accounts.get(@access_token)

# Pull the accounts associated with the Item
# associated with the Item is available
response = client.Accounts.get(access_token)
accounts = response['accounts']

// Pull the accounts associated with the Item
client.getAccounts(ACCESS_TOKEN, (err, result) => {
 // Handle err
 // High-level information about each account associated with the Item is available
 const accounts = result.accounts;
});

// Pull the accounts associated with the Item
Response<AccountsGetResponse> response = client().service().accountsGet(
 new AccountsGetRequest("ACCESS_TOKEN"))
 .execute();
List<Account> accounts = response.body().getAccounts();

Retrieve Accounts Response

http code 200
{
 "accounts": [{
   "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
   "balances": {
     "available": 100,
     "current": 110,
     "limit": null
   },
   "mask": "0000",
   "name": "Plaid Checking",
   "official_name": "Plaid Gold Checking",
   "subtype": "checking",
   "type": "depository"
 }, {
   "account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",
   "balances": {
     "available": null,
     "current": 410,
     "limit": 2000
   },
   "mask": "3333",
   "name": "Plaid Credit Card",
   "official_name": "Plaid Diamond Credit Card",
   "subtype": "credit card",
   "type": "credit"
 }],
 "item": {Object},
 "request_id": "45QSn"
}

Retrieve Transactions

POST /transactions/get

Retrieve Transactions Request

curl -X POST https://sandbox.plaid.com/transactions/get \
-H 'content-type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_token": String,
 "start_date": "2017-01-01",
 "end_date": "2017-02-01",
 "options": {
   "count": 250,
   "offset": 100
 }
}'

# Pull transactions by date and filter by an account ID
response = @client.transactions.get(@access_token,
                                   '2017-01-01',
                                   '2017-01-01',
                                   account_ids: [account_id])
# Manipulate the `count` and `offset parameters to paginate transactions
# and retrieve all available data
response = @client.transactions.get(@access_token,
                                   '2016-01-01',
                                   '2017-01-01',
                                   count: 250,
                                   offset: 0)
total_transactions = response['total_transactions']

// Retrieve transactions from Jan 1 until Feb 15
// NOTE: This endpoint may return a `PRODUCT_NOT_READY` error if transactions
// are not yet processed for the Item.
client.getTransactions(accessToken, '2017-01-01', '2017-02-15', {
 count: 250,
 offset: 0,
}, (err, result) => {
 // Handle err
 const transactions = result.transactions;
});

response = client.Transactions.get(access_token, start_date='2016-07-12', end_date='2017-01-09')
transactions = response['transactions']

# the transactions in the response are paginated, so make multiple calls while increasing the offset to
# retrieve all transactions
while len(transactions) < response['total_transactions']:
   response = client.Transactions.get(access_token, start_date='2016-07-12', end_date='2017-01-09',
                                      offset=len(transactions)
                                     )
   transactions.extend(response['transactions'])

SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");
startDate = simpleDateFormat.parse("2017-01-01");
endDate = simpleDateFormat.parse("2017-02-01");

Response<TransactionsGetResponse> response = client().service().transactionsGet(
 new TransactionsGetRequest(
   "ACCESS_TOKEN",
   startDate,
   endDate))
 .execute();

Response<TransactionsGetResponse> response = client().service().transactionsGet(
 new TransactionsGetRequest(
   accessToken,
   startDate,
   endDate)
   .withAccountIds(Arrays.asList(someAccountId))
   .withCount(numTxns)
   .withOffset(1)).execute();

for (TransactionsGetResponse.Transaction txn : response.body().getTransactions()) { ... }

Retrieve Transactions Response

http code 200
{
"accounts": [{object}],
"transactions": [{
   "account_id": "vokyE5Rn6vHKqDLRXEn5fne7LwbKPLIXGK98d",
   "amount": 2307.21,
   "category": [
     "Shops",
     "Computers and Electronics"
   ],
   "category_id": "19013000",
   "date": "2017-01-29",
   "location": {
    "address": "300 Post St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94108",
    "lat": null,
    "lon": null
   },
   "name": "Apple Store",
   "payment_meta": Object,
   "pending": false,
   "pending_transaction_id": null,
   "account_owner": null,
   "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
   "transaction_type": "place"
  }, {
   "account_id": "XA96y1wW3xS7wKyEdbRzFkpZov6x1ohxMXwep",
   "amount": 78.5,
   "category": [
     "Food and Drink",
     "Restaurants"
   ],
   "category_id": "13005000",
   "date": "2017-01-29",
   "location": {
     "address": "262 W 15th St",
     "city": "New York",
     "state": "NY",
     "zip": "10011",
     "lat": 40.740352,
     "lon": -74.001761
   },
   "name": "Golden Crepes",
   "payment_meta": Object,
   "pending": false,
   "pending_transaction_id": null,
   "account_owner": null,
   "transaction_id": "4WPD9vV5A1cogJwyQ5kVFB3vPEmpXPS3qvjXQ",
   "transaction_type": "place"
 }],
 "item": {Object},
 "total_transactions": Number,
 "request_id": "45QSn"
}

Retrieve Identity

POST /identity/get

curl -X POST https://sandbox.plaid.com/identity/get \
-H 'content-type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_token": String
}'

# Pull identity data for an item
response = @client.identity.get(@access_token)

# Pull identity data for an item
response = client.Identity.get(access_token)
identity = response['identity']

// Retrieve Identity data for an Item
client.getIdentity(accessToken, function(err, result) {
 // Handle err
 const info = result.info;
});

// Retrieve Identity data for an Item
Response<IdentityGetResponse> response = client().service().identityGet(
 new IdentityGetRequest("ACCESS_TOKEN")
).execute();
IdentityGetResponse.Identity info = response.body().getIdentity();

Retrieve Identity Response

http code 200
{
 "accounts": [{object}],
 "identity": {
   "addresses": [
     {
       "accounts": [
         "Plaid Checking 0000",
         "Plaid Saving 1111",
         "Plaid CD 2222"
       ],
       "data": {
         "city": "Malakoff",
         "state": "NY",
         "street": "2992 Cameron Road",
         "zip": "14236"
       },
       "primary": true
     },
     {
       "accounts": [
         "Plaid Credit Card 3333"
       ],
       "data": {
         "city": "San Matias",
         "state": "CA",
         "street": "2493 Leisure Lane",
         "zip": "93405-2255"
       },
       "primary": false
     }
   ],
   "emails": [
     {
       "data": "accountholder0@example.com",
       "primary": true,
       "type": "primary"
     }
   ],
   "names": [
     "Alberta Bobbeth Charleson"
   ],
   "phone_numbers": [{
     "primary": true,
     "type": "home",
     "data": "4673956022"
   }],
 },
 "item": {object},
 "request_id": "dd4K4"
}

Get Income

POST /income/get

Get Income request

curl -X POST https://sandbox.plaid.com/income/get \
-H 'content-type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_token": String
}'

# retrieve Income data for an Item
income_response = client.income.get(access_token)

# retrieve Income data for an Item
income_response = client.Income.get(access_token)

// Retrieve Income data for an Item
client.getIncome(accessToken, function(err, result) {
 // Handle err
 var income = result.income;
});

// Retrieve Income data for an Item
Response<IncomeGetResponse> response =
 client().service().incomeGet(new IncomeGetRequest(ACCESS_TOKEN)).execute();
Income income = response.getIncome();
List<IncomeStreams> incomeStreams = income.getIncomeStreams();

Get Income response

http code 200
{
 "item": {Object},
 "income": {
   "income_streams": [
     {
       "confidence": 1,
       "days": 518,
       "monthly_income": 1601,
       "name": "PLAID"
     },
     {
       "confidence": 0.95,
       "days": 415,
       "monthly_income": 1530,
       "name": "BAGUETTES INC"
     }
   ],
   "last_year_income": 28072,
   "last_year_income_before_tax": 38681,
   "projected_yearly_income": 19444,
   "projected_yearly_income_before_tax": 26291,
   "max_number_of_overlapping_income_streams": 2,
   "number_of_income_streams": 2
 },
 "request_id": "x9a1xa"
}

Get Balance

POST /accounts/balance/get

Get Balance Submit

curl -X POST https://sandbox.plaid.com/accounts/balance/get \
-H 'content-type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_token": String
 "options": {
   "account_ids": [String],
 }
}'

# Pull real-time balance information for each
# account associated with the Item
response = @client.accounts.balance.get(@access_token)

# Pull real-time balance information for each
# account associated with the Item
response = client.Accounts.balance.get(access_token)
// Each account has up-to-date balance information associated with it
accounts = response['accounts']

// Pull real-time balance information for each account associated with the Item
client.getBalance(ACCESS_TOKEN, (err, result) => {
 // Handle err
 // Each account has up-to-date balance information associated with it
 const item = result.accounts;
});

Response<AccountsBalanceGetResponse> response = client().service().accountsBalanceGet(
 new AccountsBalanceGetRequest("ACCESS_TOKEN"))
 .execute();
List<Account> accounts = response.body().getAccounts();

http code 200
{
 "accounts": [{
    "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv",
    "balances": {
      "available": 100,
      "current": 110,
      "limit": null
    },
    "mask": "0000",
    "name": "Plaid Checking",
    "official_name": "Plaid Gold Checking",
    "subtype": "checking",
    "type": "depository"
 }],
 "item": {object},
 "request_id": "1zlMf"
}

Get Item

POST /item/get

curl -X POST https://sandbox.plaid.com/item/get \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": String
 }'

# Pull information about the Item
response = client.item.get(access_token)
item = response['item']

# Pull information about the Item
response = client.Item.get(access_token)
item = response['item']

// Pull information about the Item
client.getItem(ACCESS_TOKEN, (err, result) => {
 // Handle err
 // The Item has a list of available products, billed products, error status,
 // webhook information, and more.
 const item = result.item;
});

// Pull information about the Item
Response<ItemGetResponse> response =
 client().service().itemGet(new ItemGetRequest("ACCESS_TOKEN")).execute();
// The Item has a list of available products, billed products, error status,
// webhook information, and more.
Item item = response.body().getItem();

Get Item Response

http code 200
{
 "item": {
   "available_products": [
     "balance",
     "auth"
   ],
   "billed_products": [
     "identity",
     "transactions"
   ],
   "error": null,
   "institution_id": "ins_109508",
   "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
   "webhook": "https://plaid.com/example/hook"
 },
 "request_id": "qpCtl"
}

Update Webhook

POST /item/webhook/update

Update Webhook request

curl -X POST https://sandbox.plaid.com/item/webhook/update \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": String,
   "webhook": "https://plaid.com/updated/hook"
 }'

# Update the webhook associated with an Item
webhook_response = client.item.webhook.update(item['access_token'],
                                             'https://my-new-webhook.com/plaid-webhook')

# Update the webhook associated with an Item
webhook_response = client.Item.webhook.update(
   access_token, 'https://my-new-webhook.com/plaid-webhook')

client.updateItemWebhook(ACCESS_TOKEN, "https://my-new-webhook.com/plaid-webhook", (err, result) => {
 // Handle err
 // A successful response indicates that the webhook has been updated. An
 // acknowledgement webhook will also be fired.
 const item = result.item;
});

Response<ItemWebhookUpdateResponse> webhookResponse = client().service().itemWebhookUpdate(
   new ItemWebhookUpdateRequest(ACCESS_TOKEN, "https://my-new-webhook.com/plaid-webhook")).execute();
ItemStatus itemStatus = webhookResponse.body().getItem();
String webhook = itemStatus.getWebhook();

Update Webhook Response

http code 200
{
 "item": {
   "available_products": [
     "balance",
     "auth"
   ],
   "billed_products": [
     "identity",
     "transactions"
   ],
   "error": null,
   "institution_id": "ins_109508",
   "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
   "webhook": "https://plaid.com/updated/webhook"
 },
 "request_id": "qpCtl"
}

Rotate Access Token

POST /item/access_token/invalidate

curl -X POST https://sandbox.plaid.com/item/access_token/invalidate \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": String
 }'

# Generate a new access_token for an Item and invalidate the old one
response = client.item.access_token.invalidate(access_token)
# Store the new access_token in a persistent, secure datastore
new_access_token = response['acccess_token']

# Generate a new access_token for an Item and invalidate the old one
response = client.Item.access_token.invalidate(access_token)
# Store the new access_token in a persistent, secure datastore
new_access_token = response['acccess_token']

// Generate a new access_token for an Item and invalidate the old one
client.invalidateAccessToken(ACCESS_TOKEN, (err, result) => {
 // Handle err
 // Store the new access_token in a persistent, secure datastore
 const accessToken  = result.access_token;
});

Response<ItemAccessTokenInvalidateResponse> response = client().service().itemAccessTokenInvalidate(
 new ItemAccessTokenInvalidateRequest("ACCESS_TOKEN")).execute();

String newAccessToken;
if (response.isSuccessful()) {
 newAccessToken = response.body().getNewAccessToken();
}

Rotate Access Token Response

http code 200
{
 "new_access_token": "access-sandbox-7c69d345-fd46",
 "request_id": "ou2XQ"
}

Update Access Token version

POST /item/access_token/update_version

curl -X POST https://sandbox.plaid.com/item/access_token/update_version \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token_v1": String
 }'

# generate an updated access token for the legacy token
response = client.item.access_token.update_version(LEGCAY_TOKEN)
# The response includes an access token compatible with Plaid's new API.
# The old access token will still work with Plaid's legacy API endpoints.
# Store the new access_token in a persistent, secure data store.
newAccessToken = response['access_token']

# generate an updated access token for the legacy token
response = client.Item.access_token.update_version(LEGCAY_TOKEN)
# The response includes an access token compatible with Plaid's new API.
# The old access token will still work with Plaid's legacy API endpoints.
# Store the new access_token in a persistent, secure data store.
newAccessToken = response.access_token

// Generate an updated access token for the legacy token
client.updateAccessTokenVersion(legacy_token, (err, result) => {
 // Handle err
 // The response includes an access token compatible with Plaid's new API.
 // The old access token will still work with Plaid's legacy API endpoints.
 // Store the new access_token in a persistent, secure data store.
 const newAccessToken = result.access_token;
});

// Generate an updated access token for the legacy token
Response<ItemAccessTokenUpdateVersionResponse> response = client().service().itemAccessTokenUpdateVersion(
 new ItemAccessTokenUpdateVersionRequest("LEGACY_ACCESS_TOKEN"))
 .execute();

String newAccessToken;
if (response.isSuccessful()) {
 // The response includes an access token compatible with Plaid's new API.
 // The old access token will still work with Plaid's legacy API endpoints.
 // Store the new access_token in a persistent, secure data store.
 newAccessToken = response.body().getAccessToken();
}

Update Access Token version response

http code 200
{
 "access_token": "access-sandbox-x9v2d345-as9c",
 "item_id": "XkW36J3gewh9wE69VkyzSxyXwEBewBio4wwJ3",
 "request_id": "c92aB"
}

Delete Item

POST /item/delete

curl -X POST https://sandbox.plaid.com/item/delete \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": String
 }'

# Provide the access token for the Item you want to delete
client.item.delete(access_token)

# Provide the access token for the Item you want to delete
response = client.Item.delete(access_token)

client.deleteItem(ACCESS_TOKEN, (err, result) => {
 // Handle err
 // The Item has been deleted and the
 // access token is now invalid
 const isDeleted = result.deleted;
});

Response<ItemDeleteResponse> response = client().service().itemDelete(
 new ItemDeleteRequest(getItemCreateResponse().getAccessToken())
).execute();
// The Item has been deleted and the access token is now invalid
Boolean isDelete = response.body().getDeleted();

Delete Item Response

http code 200
{
 "deleted": true,
 "request_id": String,
}

Error schema

{
 "error_type": String,
 "error_code": String,
 "error_message": String,
 "display_message": String
}

Error type

INVALID_REQUEST

Invalid request error

{
 "error_type": "INVALID_REQUEST",
 "http_code": Enum (400, 404),
 "error_code": Enum (
   "MISSING_FIELDS",
   "UNKNOWN_FIELDS",
   "INVALID_FIELD",
   "INVALID_BODY",
   "INVALID_HEADERS",
   "NOT_FOUND",
   "SANDBOX_ONLY"
 )
 "error_message": String
 "display_message": Null,
 "request_id": String
}

Error type

INVALID_INPUT

Invalid input error

{
 "error_type": "INVALID_INPUT",
 "http_code": 400,
 "error_code": Enum (
   "INVALID_API_KEYS",
   "INVALID_ACCESS_TOKEN",
   "INVALID_PUBLIC_TOKEN",
   "UNAUTHORIZED_PRODUCT",
   "INVALID_ACCOUNT_ID",
   "INVALID_INSTITUTION"
 )
 "error_message": String
 "display_message": Null,
 "request_id": String
}

Error type

RATE_LIMIT_EXCEEDED

Rate limit error schema

{
 "error_type": "RATE_LIMIT_EXCEEDED",
 "http_code": 429,
 "error_code": Enum (
   "ADDITION_LIMIT",
   "AUTH_LIMIT",
   "TRANSACTIONS_LIMIT",
   "IDENTITY_LIMIT",
   "INCOME_LIMIT",
   "ITEM_GET_LIMIT",
   "RATE_LIMIT"
 )
 "error_message": String
 "display_message": nullable String,
 "request_id": String
}

Error type

API_ERROR

API error schema

{
 "error_type": "API_ERROR",
 "http_code": 500,
 "error_code": Enum (
   "INTERNAL_SERVER_ERROR",
   "PLANNED_MAINTENANCE"
 )
 "error_message": String
 "display_message": nullable String,
 "request_id": String
}

Error type

ITEM_ERROR

Item error schema

{
 "error_type": "ITEM_ERROR",
 "http_code": 400,
 "error_code": Enum (
   "INVALID_CREDENTIALS",
   "INVALID_MFA",
   "ITEM_LOCKED",
   "ITEM_LOGIN_REQUIRED",
   "ITEM_NO_ERROR",
   "ITEM_NOT_SUPPORTED",
   "USER_SETUP_REQUIRED",
   "MFA_NOT_SUPPORTED",
   "NO_ACCOUNTS",
   "NO_AUTH_ACCOUNTS",
   "PRODUCT_NOT_READY"
 )
 "error_message": String
 "display_message": nullable String,
 "request_id": String
}

Error type

INSTITUTION_ERROR

Institution error schema

{
 "error_type": "INSTITUTION_ERROR",
 "http_code": 400,
 "error_code": Enum (
   "INSTITUTION_DOWN",
   "INSTITUTION_NOT_RESPONDING",
   "INSTITUTION_NOT_AVAILABLE",
   "INSTITUTION_NO_LONGER_SUPPORTED"
 )
 "error_message": String
 "display_message": nullable String,
 "request_id": String
}

Webhook Body

Initial Transaction Webhook

{
 "webhook_type": "TRANSACTIONS",
 "webhook_code": "INITIAL_UPDATE",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null,
 "new_transactions": 19
}

Historical Transaction Webhook

{
 "webhook_type": "TRANSACTIONS",
 "webhook_code": "HISTORICAL_UPDATE",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null,
 "new_transactions": 231
}

Default Transaction Webhook

{
 "webhook_type": "TRANSACTIONS",
 "webhook_code": "DEFAULT_UPDATE",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null,
 "new_transactions": 3
}

Removed Transaction Webhook

{
 "webhook_type": "TRANSACTIONS",
 "webhook_code": "TRANSACTIONS_REMOVED",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "removed_transactions": [
   "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
   "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
 ],
 "error": null
}

Item's Webhook Updated

{
 "webhook_type": "ITEM",
 "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null
}

Item's Webhook Updated

{
 "webhook_type": "ITEM",
 "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null,
 "new_webhook": "https://plaid.com/example/webhook"
}

Error Response Webhook Example

{
 "webhook_type": "ITEM",
 "webhook_code": "ERROR",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": {
   "display_message": "The provided credentials were not correct. Please try again.",
   "error_code": "ITEM_LOGIN_REQUIRED",
   "error_message": "the provided credentials were not correct",
   "error_type": "ITEM_ERROR",
   "status": 400
 }
}

Income ready webhook

{
 "webhook_type": "INCOME",
 "webhook_code": "PRODUCT_READY",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null
}

Institutions endpoints

POST /institutions/get
POST /institutions/get_by_id
POST /institutions/search

Institution search

POST /institutions/search

Search by Bank and Product

curl -X POST https://sandbox.plaid.com/institutions/search \
 -H 'content-type: application/json' \
 -d '{
   "query": "BB&T",
   "products": ["auth", "identity"],
   "public_key": String
 }'

response = client.institutions.search(SEARCH_QUERY)
# search with products
response = client.institutions.search(SEARCH_QUERY, [:transactions])

response = client.Institutions.search(SEARCH_QUERY)
# search with products
response = client.Institutions.search(SEARCH_QUERY, products=['transactions'])

client.searchInstitutionsByName(SEARCH_QUERY, ['transactions'],
function(err, response) {
 // Handle err
 institutions = response.institutions;
});

Response<InstitutionsSearchResponse> response =
 client().service().institutionsSearch(new InstitutionsSearchRequest(SEARCH_QUERY).withProducts(Product.AUTH)).execute();
List<Institution> results = response.body().getInstitutions();

Institutions search response

http code 200
{
 "institutions": [{
   "credentials": [{
     "label": "User ID",
     "name": "username",
     "type": "text"
   }, {
     "label": "Password",
     "name": "password",
     "type": "password"
   }],
   "has_mfa": true,
   "institution_id": "ins_109509",
   "mfa": [
     "code",
     "list",
     "questions",
     "selections"
   ],
   "name": "First Gingham Credit Union",
   "products": [
     "balance",
     "identity",
     "auth",
     "transactions"
   ]
 }],
 "request_id": "DLVvK"
}

All Institutions

POST /institutions/get

Get all Institutions

curl -X POST https://sandbox.plaid.com/institutions/get \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret":String,
   "count": Number,
   "offset": Number
 }'

response = client.institutions.get(count: count, offset: offset)
institutions = response['institutions']

response = client.Institutions.get(count, offset=offset)
institutions = response['institutions']

// Pull institutions
client.getInstitutions(count, offset, (err, result) => {
 // Handle err
 const institutions = result.institutions;
});

Response<InstitutionsGetResponse> response =
 client().service().institutionsGet(new InstitutionsGetRequest(count, offset)).execute();
List<Institution> institutions = response.body().getInstitutions();

All Institutions response

http code 200
{
 "institutions": [
   {
     "credentials": [{
       "label": "User ID",
       "name": "username",
       "type": "text"
      }, {
       "label": "Password",
       "name": "password",
       "type": "password"
     }],
     "has_mfa": true,
     "institution_id": "ins_109508",
     "mfa": [
       "code",
       "list",
       "questions",
       "selections"
     ],
     "name": "First Platypus Bank",
     "products": [
       "balance",
       "identity",
       "auth",
       "transactions"
     ]
   }, {
   "credentials": [{
     "label": "User ID",
     "name": "username",
     "type": "text"
   }, {
     "label": "Password",
     "name": "password",
     "type": "password"
   }],
   "has_mfa": true,
   "institution_id": "ins_109509",
   "mfa": [
     "code",
     "list",
     "questions",
     "selections"
   ],
   "name": "First Gingham Credit Union",
   "products": [
     "balance",
     "identity",
     "auth",
     "transactions"
   ]
 }],
 "request_id": "lHkKq",
 "total": 5
}

Institutions by ID

POST /institutions/get_by_id

Institutions by ID request

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
 -H 'content-type: application/json' \
 -d '{
   "institution_id": "ins_109512",
   "public_key": String
 }'

response = client.institutions.get_by_id(INSTITUTION_ID)

response = client.Institutions.get_by_id(INSTITUTION_ID)

// Pull institution by ID
client.getInstitutionById(institutionId, (err, result) => {
 // Handle err
 const institution = result.institution;
});

// Pull institution by ID
Response<InstitutionsGetByIdResponse> response = client().service().institutionsGetById(new InstitutionsGetByIdRequest(INSTITUTION_ID))
 .execute();
Institution institution = response.body().getInstitution();

Institutions by ID Response

http code 200
{
 "institution": {
   "credentials": [{
     "label": "User ID",
     "name": "username",
     "type": "text"
    }, {
     "label": "Password",
     "name": "password",
     "type": "password"
   }],
   "has_mfa": true,
   "institution_id": "ins_109512",
   "mfa": [
     "code",
     "list",
     "questions",
     "selections"
   ],
   "name": "Houndstooth Bank",
   "products": [
     "auth",
     "balance",
     "identity",
     "transactions"
   ]
 },
 "request_id": "9VpnU"
}

Category

POST /categories/get

All Categories request

curl -X POST https://sandbox.plaid.com/categories/get \
 -H 'content-type: application/json' \
 -d '{}'

response = client.categories.get()
categories = response['categories']
`

response = client.Categories.get()
categories = response['categories']
`

client.getCategories(function(err, response) {
 // Handle err
 var categories = response.categories;
});

Response<CategoriesGetResponse> response = client().service().categoriesGet(
 new CategoriesGetRequest()
).execute()
List<Category> categories = response.body().getCategories();
`

All Categories response

http code 200
{
 "categories": [
   {
     "group": "place",
     "hierarchy": [
       "Recreation",
       "Arts & Entertainment",
       "Circuses and Carnivals"
     ],
     "category_id": "17001013"
   },
   ...
 ],
 "request_id": "qpCtl"
}

Sandbox API host

https://sandbox.plaid.com

Retrieve all Institutions

curl -X POST https://sandbox.plaid.com/institutions/get \
-H 'Content-type: application/json' \
-d '{
 "client_id": "[PUBLIC_KEY]",
 "secret": "[SECRET]",
 "count": 200,
 "offset": 0
}'

Retrieve Tartan Bank (institution_id: ins_109511)

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
-H 'Content-type: application/json' \
-d '{
 "public_key": "[PUBLIC_KEY]",
 "institution_id": "ins_109511"
}'

Simulate Item error

POST /sandbox/item/reset_login

Sandbox reset Item login request

curl -X POST https://sandbox.plaid.com/sandbox/item/reset_login \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": String
 }'

# Force a Sandbox Item into an error state
client.sandbox.sandbox_item.reset_login(access_token)
# create a public_token for the Item and use it to initialize Link in
# update mode.
public_token_response = client.item.public_token.create(access_token)

# Force a Sandbox Item into an error state
client.Sandbox.item.reset_login(access_token)
# create a public_token for the Item and use it to initialize Link in
# update mode.
public_token_response = client.Item.public_token.create(access_token)

client.resetLogin(access_token, function(err, reset_login_response) {
 // Handle err
 // create a public_token for the Item
 client.createPublicToken(access_token, function(err, public_token_response) {
   // Handle err
   // Use the generated public_token to
   // initialize Link in update mode
 });
});

Response<ItemResetLoginResponse> response = client().service().itemResetLogin(
 new ItemResetLoginRequest(ACCESS_TOKEN)
).execute();

Sandbox reset Item login response

http code 200
{
 "reset_login": true,
 "request_id": String
}