Build

Create an Asset Report

Learn how to create Asset Reports with the Assets product

In this guide, we'll start from scratch and walk through how to use Assets to generate and retrieve Asset Reports. If a user's Asset Report involves data from multiple financial institutions, the user will need to allow access to each institution, which will in turn enable you to access their data from each institution. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Creating Asset Reports.

Get Plaid API keys

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid developer dashboard.

Install Plaid libraries

You can use our official libraries to connect to the Plaid API from your application:

1
2
# Install via npm
npm install --save plaid

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. 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. Asset Reports can consist of user data from multiple financial institutions; users will need to use Link to provide access to each financial institution, providing you with multiple Items. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created. Since, for Assets, users may need to grant access to more than one financial institution via Link, you may need to initialize Link more than once.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard.

Create a link_token
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Using Express
const 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('/get_link_token', async (request, response) => {
try {
// Get the client_user_id by searching for the current user
const user = await User.find(...);
const clientUserId = user.id;
// Create the link_token with all of your configurations
const tokenResponse = await client.createLinkToken({
user: {
client_user_id: clientUserId,
},
client_name: 'My App',
products: ['assets'],
country_codes: ['US'],
language: 'en',
webhook: 'https://webhook.sample.com',
});
response.on({ link_token: tokenResponse.link_token });
} catch (e) {
// Display error on client
return response.send({ error: e.message });
}
});
Install Link dependency
1
2
3
4
<head>
<title>Connect a bank</title>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
</head>
Configure the client-side Link handler
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const linkHandler = Plaid.create({
token: await $.post('/get_link_token'),
onSuccess: (public_token, metadata) => {
// Send the public_token to your app server.
$.post('/get_access_token', {
public_token: public_token,
});
},
onExit: (err, metadata) => {
// Optionally capture when your user exited the Link flow.
// Storing this information can be helpful for support.
},
onEvent: (eventName, metadata) => {
// Optionally capture Link flow events, streamed through
// this callback as your users connect an Item to Plaid.
},
});
linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id for each Item the user provided you with via Link. The access_token will allow us to make authenticated calls to the Plaid API for its corresponding financial institution. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_tokens and item_ids in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. An access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. An access_token should be stored securely and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Using Express
const 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('/get_access_token', async (request, response) => {
try {
const PUBLIC_TOKEN = request.body.public_token;
// Exchange the client-side public_token for a server access_token
const tokenResponse = await client.exchangePublicToken(PUBLIC_TOKEN);
// Save the access_token and item_id to a persistent database
const ACCESS_TOKEN = tokenResponse.access_token;
const ITEM_ID = tokenResponse.item_id;
} catch (e) {
// Display error on client
return response.send({ error: e.message });
}
});

Creating Asset Reports

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and create an Asset Report using the /asset_report/create endpoint.

Assets sample request: create
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
const daysRequested = 60;
const options = {
client_report_id: '123',
webhook: 'https://www.example.com',
user: {
client_user_id: '789',
first_name: 'Jane',
middle_name: 'Leah',
last_name: 'Doe',
ssn: '123-45-6789',
phone_number: '(555) 123-4567',
email: 'jane.doe@example.com',
},
};
// accessTokens is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
const response = await client
.createAssetReport(accessTokens, daysRequested, options)
.catch((err) => {
// handle error
});
const assetReportId = response.asset_report_id;
const assetReportToken = response.asset_report_token;

Sample response data is below.

1
2
3
4
5
{
"asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
"asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
"request_id": "Iam3b"
}

Fetching asset data

Once an Asset Report has been created, it can be retrieved to analyze the user's loan eligibility. For more detailed information on the schema for Asset Reports returned by /asset_report/get, see the Assets Reference.

Asset Reports are not generated instantly. If you receive a PRODUCT_NOT_READY error when calling /asset_report/get, the requested Asset Report has not yet been generated. To be alerted when the requested Asset Report has been generated, listen to Assets webhooks.

Assets sample request: get
1
2
3
4
5
6
7
8
9
const accountIdsToExclude = ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'];
const response = await client
.filterAssetReport(assetReportToken, accountIdsToExclude)
.catch((err) => {
// handle error
});
const assetReportId = response.asset_report_id;
const assetReportToken = response.asset_report_token;

Sample response data is below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
{
"report": {
"asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
"client_report_id": "123abc",
"date_generated": "2020-06-05T22:47:53Z",
"days_requested": 2,
"items": [
{
"accounts": [
{
"account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
"balances": {
"available": 200,
"current": 210,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"days_available": 2,
"historical_balances": [
{
"current": 210,
"date": "2020-06-04",
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
{
"current": 210,
"date": "2020-06-03",
"iso_currency_code": "USD",
"unofficial_currency_code": null
}
],
"mask": "1111",
"name": "Plaid Saving",
"official_name": "Plaid Silver Standard 0.1% Interest Saving",
"owners": [
{
"addresses": [
{
"data": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"primary": true
},
{
"data": {
"city": "San Matias",
"country": "US",
"postal_code": "93405-2255",
"region": "CA",
"street": "2493 Leisure Lane"
},
"primary": false
}
],
"emails": [
{
"data": "accountholder0@example.com",
"primary": true,
"type": "primary"
},
{
"data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
"primary": false,
"type": "other"
}
],
"names": ["Alberta Bobbeth Charleson"],
"phone_numbers": [
{
"data": "1112223333",
"primary": false,
"type": "home"
},
{
"data": "1112225555",
"primary": false,
"type": "mobile1"
}
]
}
],
"ownership_type": null,
"subtype": "savings",
"transactions": [],
"type": "depository"
},
{
"account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
"balances": {
"available": null,
"current": 56302.06,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"days_available": 2,
"historical_balances": [],
"mask": "8888",
"name": "Plaid Mortgage",
"official_name": null,
"owners": [
{
"addresses": [
{
"data": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"primary": true
},
{
"data": {
"city": "San Matias",
"country": "US",
"postal_code": "93405-2255",
"region": "CA",
"street": "2493 Leisure Lane"
},
"primary": false
}
],
"emails": [
{
"data": "accountholder0@example.com",
"primary": true,
"type": "primary"
},
{
"data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
"primary": false,
"type": "other"
}
],
"names": ["Alberta Bobbeth Charleson"],
"phone_numbers": [
{
"data": "1112223333",
"primary": false,
"type": "home"
},
{
"data": "1112225555",
"primary": false,
"type": "mobile1"
}
]
}
],
"ownership_type": null,
"subtype": "mortgage",
"transactions": [],
"type": "loan"
},
{
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
"balances": {
"available": null,
"current": 410,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"days_available": 2,
"historical_balances": [
{
"current": 410,
"date": "2020-06-04",
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
{
"current": 410,
"date": "2020-06-03",
"iso_currency_code": "USD",
"unofficial_currency_code": null
}
],
"mask": "3333",
"name": "Plaid Credit Card",
"official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
"owners": [
{
"addresses": [
{
"data": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"primary": true
},
{
"data": {
"city": "San Matias",
"country": "US",
"postal_code": "93405-2255",
"region": "CA",
"street": "2493 Leisure Lane"
},
"primary": false
}
],
"emails": [
{
"data": "accountholder0@example.com",
"primary": true,
"type": "primary"
},
{
"data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
"primary": false,
"type": "other"
}
],
"names": ["Alberta Bobbeth Charleson"],
"phone_numbers": [
{
"data": "1112223333",
"primary": false,
"type": "home"
},
{
"data": "1112225555",
"primary": false,
"type": "mobile1"
}
]
}
],
"ownership_type": null,
"subtype": "credit card",
"transactions": [],
"type": "credit"
}
],
"date_last_updated": "2020-06-05T22:47:52Z",
"institution_id": "ins_3",
"institution_name": "Chase",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
}
],
"user": {
"client_user_id": "123456789",
"email": "accountholder0@example.com",
"first_name": "Alberta",
"last_name": "Charleson",
"middle_name": "Bobbeth",
"phone_number": "111-222-3333",
"ssn": "123-45-6789"
}
},
"request_id": "eYupqX1mZkEuQRx",
"warnings": []
}

Working with Assets data

After your inital /asset_report/create and /asset_report/get requests, you may want your application to fetch updated Asset Reports, provide Audit Copies of Asset Reports, and more. Consult the API Reference to explore these and other options.