Introduction to Assets

Learn how to use Assets to access users' financial information for loan underwriting.

Explore API

API Reference

View Assets requests, responses, and example code

View Assets API

Quickstart

Learn about Plaid's key concepts and run starter code

Get started

Overview

Assets data is used to determine whether a user has enough assets to qualify for a loan. Plaid's Assets product allows you to access a user's Asset Report via the /asset_report/get (JSON) and /asset_report/pdf/get (PDF) endpoints. Asset Reports are created on a per-user basis and include a snapshot of information about a user's identity, transaction history, account balances, and more.


Assets flow

There are a few steps you will need to take to obtain an Asset Report for a particular user.

  1. First, using Link, create Items for each of the user's financial institutions; in doing so, you will obtain an access_token for each institution. You can use these tokens to obtain an Asset Report as long as the access_token was generated with assets included in Link's product array. With Assets, the user, upon using Link to authenticate with their financial institution, will need to provide consent for Plaid to access account balances, account holder information, and transaction history for that institution. Should the user revoke access via my.plaid.com, Plaid will notify you via a webhook.

  2. Once you have the required access_tokens, call the /asset_report/create endpoint to create an Asset Report. Note that Asset Reports are not created instantly.

  3. To retrieve an Asset Report in JSON format, call the /asset_report/get endpoint. To retrieve an Asset Report in PDF format, call the /asset_report/pdf/get endpoint. Note that Asset Reports are not created instantly; listen to assets webhooks to be notified when a requested Asset Report is ready. To retrieve an Asset Report with cleaned and categorized transactions as well as additional information about merchants and locations in JSON format, call the /asset_report/get endpoint with include_insights=true. You will need to request product access to use include_insights.

  4. Sometimes, third party auditors need to see Asset Reports to audit lenders' decision making processes. To provide an Audit Copy of an Asset Report to a requesting third party, call the /asset_report/audit_copy/create endpoint and provide the auditor with an audit_copy_token. The auditor needs to be integrated with Plaid in order to view Audit Copies. Currently, Fannie Mae and Ocrolus are the only auditors integrated with Plaid.

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": []
}

The report field of the above object contains the body of the Asset Report. This field consists of several subfields that contain information about the date and time the Asset Report was created; data submitted about the user; and information about Items, containing the user's historical balances, identity information, and more for each of the user's financial institutions. For a full explanation of the report field and its subfields, consult the API Reference.

Assets webhooks

When you create an Asset Report, Plaid aggregates account balances, account holder identity information, and transaction history for the duration specified. If you attempt to retrieve an Asset Report before the requested data has been collected, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY.

To remove the need for polling, Plaid sends a webhook to the URL you supplied when creating the Asset Report once the Report has been generated. If generation fails, the webhook will indicate why. For examples of webhooks corresponding to successful and unsuccessful Asset Report generation, see this page about assets webhooks.

Refreshing Asset Reports

Asset Reports can either be created or removed; they cannot be updated. To retrieve up-to-date information about users' transactions and balances, call the /asset_report/refresh endpoint. This endpoint, when used, creates a new Asset Report based on the corresponding existing Asset Report.

Testing Assets

Assets can be tested in Sandbox without any additional permissions. In order to test Assets against live Items in Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

Next steps

To learn more about building with Assets, visit Create an Asset Report and the API Reference.