Get started with the Quickstart
A quick introduction to building with Plaid
Not a developer? Check out the Plaid Postman Collection for a no-code way to get started with Plaid's API.
Introduction
Let’s test out running Plaid locally by cloning the Quickstart app. You’ll need API keys, which you can receive by signing up in the Dashboard.
You'll have two different API keys, and there are three different Plaid environments. Today we'll start in the Sandbox environment. View the API Keys section of the Dashboard to find your Sandbox secret.
API Key
View Keys in DashboardEnvironment
Set up the Quickstart
Once you have your API keys, it's time to run the Plaid Quickstart locally! At the command line, enter the commands below to clone the Quickstart repository and run the Quickstart. Make sure to copy .env.example
to .env
and fill out the the values for PLAID_CLIENT_ID
and PLAID_SECRET
in .env
with your own Plaid client ID and Sandbox secret.
git clone https://github.com/plaid/quickstart.gitcd quickstart/node# Copy the .env.example file to .env, then fill# out PLAID_CLIENT_ID and PLAID_SECRET in .envcp .env.example .env# Install dependenciesnpm install# Start the Quickstart appnode index.js# Go to http://localhost:8000

Setting up the Quickstart in Europe
If you'll be running the Quickstart and using European institutions, a few special instructions apply.
Some European institutions require an OAuth redirect authentication flow, where the end user is redirected to the bank’s website or mobile app to authenticate. For this flow, you should provide two additional environment variables in your .env
file.
# ...PLAID_REDIRECT_URI=http://localhost:8000/oauth-response.htmlPLAID_COUNTRY_CODES=GB # Or any supported European countries (ES, FR, GB, IE, NL)
When running in Production or Development, you will need to use an https://
redirect URI, but a localhost http URI will work fine for Sandbox.
You will also need to configure this PLAID_REDIRECT_URI
for your client ID through the Plaid developer dashboard.
git clone https://github.com/plaid/quickstart.gitcd quickstart/node# Copy the .env.example file to .env, then fill# out PLAID_CLIENT_ID, PLAID_SECRET,# PLAID_COUNTRY_CODES=GB, and# PLAID_REDIRECT_URI=http://localhost:8000/oauth-response.htmlcp .env.example .env# Install dependenciesnpm install# Start the Quickstart appnode index.js# Go to http://localhost:8000

Setting up the Quickstart for Payment Initiation (UK and Europe only)
When using the UK and Europe-only Payment Initiation product with the Quickstart, two steps are necessary in addition to following the Europe-specific setup instructions above.
First, it is necessary to specify payment_initiation
as the only product in the PLAID_PRODUCTS
environment variable in .env
. No other products can be specified when using the Payment Initiation Quickstart.
# ...PLAID_REDIRECT_URI=http://localhost:8000/oauth-response.htmlPLAID_COUNTRY_CODES=GB # Or any supported European countries (ES, FR, GB, IE, NL)PLAID_PRODUCTS=payment_initiation
In addition, the Payment Initiation product is not enabled in Sandbox by default. To run the Payment Initiation Quickstart, contact Sales to enable Payment Initiation for your account.
Create your first Item
Most API requests interact with an Item, which is a Plaid term for a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.
Now that you have the Quickstart running, you’ll add your first Item in the Sandbox environment. Once you’ve opened the Quickstart app on localhost, click the Connect with Plaid button and select any institution. Use the Sandbox credentials to simulate a successful login.
Sandbox credentials
username: user_goodpassword: pass_good
Once you have entered your credentials and moved to the next screen, you have created your first Item! You can now make API calls for that Item by using the buttons in the Quickstart. In the next section, we'll explain what actually happened and how the Quickstart works.
How it works
As you might have noticed, you use both a server and a client-side component to access the Plaid APIs. The flow looks like this:

link_token
and pass the temporary token to your app's client.
link_token
to open Link for your user. In the onSuccess
callback, send the temporary public_token
to your app's server.
public_token
for a permanent access_token
and item_id
for the new Item
.
access_token
and use it to make product requests for your user's Item
.
The first step is to create a new link_token
by making a /link/token/create
request and passing in the required configurations. This link_token
is a short lived, one-time use token that authenticates your app with Plaid Link, our frontend module. Several of the environment variables you configured when launching the Quickstart, such as PLAID_PRODUCTS
, are used as parameters for the link_token
.
// Using Expressconst express = require('express');const app = express();app.use(express.json());const plaid = require('plaid');const client = new plaid.Client({clientID: process.env.PLAID_CLIENT_ID,secret: process.env.PLAID_SECRET,env: plaid.environments.sandbox,});app.post('/create_link_token', async (request, response) => {try {// Get the client_user_id by searching for the current userconst user = await User.find(...);const clientUserId = user.id;// Create the link_token with all of your configurationsconst tokenResponse = await client.createLinkToken({user: {client_user_id: clientUserId,},client_name: 'My App',products: ['transactions'],country_codes: ['US'],language: 'en',webhook: 'https://webhook.sample.com',});response.on({ link_token: tokenResponse.link_token });} catch (e) {// Display error on clientreturn response.send({ error: e.message });}});
Once you have a link_token
, you can use it to initialize Link. Link is a drop-in client-side module available for web, iOS, and Android that handles the authentication process. The Quickstart uses Link on the web, which is a pure JavaScript integration that you trigger via your own client-side code. This is what your users use to log into their financial institution accounts.
After a user submits their credentials within Link, Link provides you with a public_token
via the onSuccess
callback. The code below shows how the Quickstart passes the public_token
from client-side code to the server.
<button id="link-button">Link Account</button><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script><script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script><script type="text/javascript">(async function($) {var handler = Plaid.create({// Create a new link_token to initialize Linktoken: (await $.post('/create_link_token')).link_token;onLoad: function() {// Optional, called when Link loads},onSuccess: function(public_token, metadata) {// Send the public_token to your app server.// The metadata object contains info about the institution the// user selected and the account ID or IDs, if the// Select Account view is enabled.$.post('/get_access_token', {public_token: public_token,});},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.},onEvent: function(eventName, metadata) {// Optionally capture Link flow events, streamed through// this callback as your users connect an Item to Plaid.// For example:// eventName = "TRANSITION_VIEW"// metadata = {// link_session_id: "123-abc",// mfa_type: "questions",// timestamp: "2017-09-14T14:42:19.350Z",// view_name: "MFA",// }}});$('#link-button').on('click', function(e) {handler.open();});})(jQuery);</script>
Next, on the server side, the Quickstart calls /item/public_token/exchange
to obtain an access_token
, as illustrated in the code excerpt below. The access_token
uniquely identifies an Item and is a required argument for most Plaid API endpoints. In your own code, you'll need to securely store your access_token
in order to make API requests for that Item.
'use strict';var util = require('util');var envvar = require('envvar');var express = require('express');var bodyParser = require('body-parser');var moment = require('moment');var plaid = require('plaid');var APP_PORT = envvar.number('APP_PORT', 8000);var PLAID_CLIENT_ID = envvar.string('PLAID_CLIENT_ID');var PLAID_SECRET = envvar.string('PLAID_SECRET');var PLAID_ENV = envvar.string('PLAID_ENV', 'sandbox');// We store the access_token in memory// In production, store it in a secure persistent data storevar ACCESS_TOKEN = null;var PUBLIC_TOKEN = null;var ITEM_ID = null;// Initialize the Plaid clientvar client = new plaid.Client({clientID: PLAID_CLIENT_ID,secret: PLAID_SECRET,env: plaid.environments[PLAID_ENV],options: { version: '2018-05-22' },});var app = express();app.use(express.static('public'));app.set('view engine', 'ejs');app.use(bodyParser.urlencoded({extended: false,}),);app.use(bodyParser.json());app.get('/', function (request, response, next) {response.render('index.ejs', {PLAID_ENV: PLAID_ENV,});});app.post('/get_access_token', function (request, response, next) {PUBLIC_TOKEN = request.body.public_token;client.exchangePublicToken(PUBLIC_TOKEN, function (error, tokenResponse) {if (error != null) {var msg = 'Could not exchange public_token!';console.log(msg + '\n' + JSON.stringify(error));return response.json({error: msg,});}ACCESS_TOKEN = tokenResponse.access_token;ITEM_ID = tokenResponse.item_id;prettyPrintResponse(tokenResponse);response.json({access_token: ACCESS_TOKEN,item_id: ITEM_ID,error: false,});});});
Making API requests
Now that we've gone over the Link flow and token exchange process, we can explore what happens when you press a button in the Quickstart to make an API call. As an example, we'll look at the Quickstart's call to /accounts/get
, which retrieves basic information, such as name and balance, about the accounts associated with an Item. The call is fairly straightforward and uses the access_token
as a single argument to the Plaid client object.
app.get('/accounts', function (request, response, next) {client.getAccounts(ACCESS_TOKEN, function (error, accountsResponse) {if (error != null) {prettyPrintResponse(error);return response.json({error: error,});}prettyPrintResponse(accountsResponse);response.json({ error: null, accounts: accountsResponse });});});
Example response data:
{"accounts": [{"account_id": "A3wenK5EQRfKlnxlBbVXtPw9gyazDWu1EdaZD","balances": {"available": 100,"current": 110,"iso_currency_code": "USD","limit": null,"unofficial_currency_code": null},"mask": "0000","name": "Plaid Checking","official_name": "Plaid Gold Standard 0% Interest Checking","subtype": "checking","type": "depository"},{"account_id": "GPnpQdbD35uKdxndAwmbt6aRXryj4AC1yQqmd","balances": {"available": 200,"current": 210,"iso_currency_code": "USD","limit": null,"unofficial_currency_code": null},"mask": "1111","name": "Plaid Saving","official_name": "Plaid Silver Standard 0.1% Interest Saving","subtype": "savings","type": "depository"},{"account_id": "nVRK5AmnpzFGv6LvpEoRivjk9p7N16F6wnZrX","balances": {"available": null,"current": 1000,"iso_currency_code": "USD","limit": null,"unofficial_currency_code": null},"mask": "2222","name": "Plaid CD","official_name": "Plaid Bronze Standard 0.2% Interest CD","subtype": "cd","type": "depository"}...],"item": {"available_products": ["assets","balance","identity","investments","transactions"],"billed_products": ["auth"],"consent_expiration_time": null,"error": null,"institution_id": "ins_12","item_id": "gVM8b7wWA5FEVkjVom3ri7oRXGG4mPIgNNrBy","webhook": "https://requestb.in"},"request_id": "C3IZlexgvNTSukt"}
Next steps
Congratulations, you have completed the Plaid Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Plaid API. There are a few directions you can go in now:
If you're not sure which Plaid products you want to use, see the Docs Home for an overview.
You can also explore building with a particular product: Auth, Transactions, Balance, Investments, Liabilities, Assets, Identity, and Payment Initiation (UK and Europe).
The Quickstart covered working with web apps. If your Plaid app will be on mobile, see Plaid Link to learn about getting started with mobile client-side setup.