Product endpoints
API reference for Plaid products
Transactions
Retrieve and refresh 24 months of historical transaction data, including geolocation, merchant, and category information.
| In this section | |
|---|---|
/transactions/get | Fetch transaction data |
/transactions/refresh | Refresh transaction data |
/categories/get | Fetch all transaction categories |
/transactions/get
Get transaction data
The /transactions/get endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype student; coverage may be limited). For transaction history from investments accounts, use the Investments endpoint instead. Transaction data is standardized across financial institutions, and in many 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.
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in /transactions/get. For more details, see Pending and posted transactions.
Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_transactions response body field to fetch all available transactions.
Data returned by /transactions/get will be the data available for the Item as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. An Item's status.transactions.last_successful_update field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, you can use the /transactions/refresh endpoint.
Note that data may not be immediately available to /transactions/get. Plaid will begin to prepare transactions data upon Item link, if Link was initialized with transactions, or upon the first call to /transactions/get, if it wasn't. To be alerted when transaction data is ready to be fetched, listen for the INITIAL_UPDATE and HISTORICAL_UPDATE webhooks. If no transaction history is ready when /transactions/get is called, it will return a PRODUCT_NOT_READY error.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | |||||
optionsobjectAn optional object to be used with the request. If specified, options must not be null.
| |||||
access_tokenrequiredstringThe access token associated with the Item data is being requested for. | |||||
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | |||||
start_daterequiredstringThe earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date | |||||
end_daterequiredstringThe latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: date |
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
const request: TransactionsGetRequest = {access_token: accessToken,start_date: '2018-01-01',end_date: '2020-02-01'};try {const response = await client.transactionsGet(request);let transactions = response.data.transactions;const total_transactions = response.data.total_transactions;// Manipulate the offset parameter to paginate// transactions and retrieve all available datawhile (transactions.length < total_transactions) {const paginatedRequest: TransactionsGetRequest = {access_token: accessToken,start_date: '2018-01-01',end_date: '2020-02-01',options: {offset: transactions.length,},};const paginatedResponse = await client.transactionsGet(paginatedRequest);transactions = transactions.concat(paginatedResponse.data.transactions,);}} catch((err) => {// handle error}
transactions/get
Response fields and example
accounts[object]An array containing the accounts associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the account_id field.
| ||||||||||||||||||||||||||||||||||||||||||
transactions[object]An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter.
| ||||||||||||||||||||||||||||||||||||||||||
total_transactionsintegerThe total number of transactions available within the date range specified. If total_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter. | ||||||||||||||||||||||||||||||||||||||||||
itemobjectMetadata about the Item.
| ||||||||||||||||||||||||||||||||||||||||||
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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
{"accounts": [{"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp","balances": {"available": 110,"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"}],"transactions": [{"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp","amount": 2307.21,"iso_currency_code": "USD","unofficial_currency_code": null,"category": ["Shops","Computers and Electronics"],"category_id": "19013000","check_number": null,"date": "2017-01-29","datetime": null,"authorized_date": "2017-01-27","authorized_datetime": null,"location": {"address": "300 Post St","city": "San Francisco","region": "CA","postal_code": "94108","country": "US","lat": 40.740352,"lon": -74.001761,"store_number": "1235"},"name": "Apple Store","merchant_name": "Apple","payment_meta": {"by_order_of": null,"payee": null,"payer": null,"payment_method": null,"payment_processor": null,"ppd_id": null,"reason": null,"reference_number": null},"payment_channel": "in store","pending": false,"pending_transaction_id": null,"account_owner": null,"transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje","transaction_code": null,"transaction_type": "place"}],"item": {"available_products": ["balance","identity","investments"],"billed_products": ["assets","auth","liabilities","transactions"],"consent_expiration_time": null,"error": null,"institution_id": "ins_3","item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6","update_type": "background","webhook": "https://www.genericwebhookurl.com/webhook"},"total_transactions": 1,"request_id": "45QSn"}
/transactions/refresh
Refresh transaction data
/transactions/refresh is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any Transactions-enabled Item. If changes to transactions are discovered after calling /transactions/refresh, Plaid will fire a webhook: TRANSACTIONS_REMOVED will be fired if any removed transactions are detected, and DEFAULT_UPDATE will be fired if any new transactions are detected. New transactions can be fetched by calling /transactions/get.
Access to /transactions/refresh in Production is specific to certain pricing plans. If you cannot access /transactions/refresh in Production, contact Sales for assistance.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
access_tokenrequiredstringThe access token associated with the Item data is being requested for. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
1
2
3
4
5
6
7
8
const request: TransactionsRefreshRequest = {access_token: accessToken,};try {await plaidClient.transactionsRefresh(request);} catch (error) {// handle error}
transactions/refresh
Response fields and example
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1
2
3
{"request_id": "1vwmF5TBQwiqfwP"}
/categories/get
Get Categories
Send a request to the /categories/get endpoint to get detailed information on categories returned by Plaid. This endpoint does not require authentication.
Request fields and example
This endpoint takes an empty request body. |
1
2
3
4
5
6
try {const response = await plaidClient.categoriesGet({});const categories = response.data.categories;} catch (error) {// handle error}
categories/get
Response fields and example
categories[object]An array of all of the transaction categories used by Plaid.
| |||
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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
{"categories": [{"category_id": "10000000","group": "special","hierarchy": ["Bank Fees"]},{"category_id": "10001000","group": "special","hierarchy": ["Bank Fees","Overdraft"]},{"category_id": "12001000","group": "place","hierarchy": ["Community","Animal Shelter"]}],"request_id": "ixTBLZGvhD4NnmB"}
Auth
Retrieve bank account information to set up electronic funds transfers, such as ACH payments in the US, EFT payments in Canada, BACS payments in the UK, and IBAN / SIC payments in the EU.
| In this section | |
|---|---|
/auth/get | Fetch account information |
/auth/get
Retrieve auth data
The /auth/get endpoint returns the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's checking and savings accounts, along with high-level account data and balances when available.
Note: This request may take some time to complete if auth was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.
Also note that /auth/get will not return data for any new accounts opened after the Item was created. To obtain data for new accounts, create a new Item.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | |
access_tokenrequiredstringThe access token associated with the Item data is being requested for. | |
optionsobjectAn optional object to filter /auth/get results.
|
1
2
3
4
5
6
7
8
9
10
const request: AuthGetRequest = {access_token: accessToken,};try {const response = await plaidClient.authGet(request);const accountData = response.data.accounts;const numbers = response.data.numbers;} catch (error) {// handle error}
auth/get
Response fields and example
accounts[object]The accounts for which numbers are being retrieved.
| ||||||||||||||||||
numbersobjectAn object containing identifying numbers used for making electronic transfers to and from the accounts. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by any accounts for which data has been requested, the array for that type will be empty.
| ||||||||||||||||||
itemobjectMetadata about the Item.
| ||||||||||||||||||
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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
{"accounts": [{"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D","balances": {"available": 100,"current": 110,"limit": null,"iso_currency_code": "USD","unofficial_currency_code": null},"mask": "9606","name": "Plaid Checking","official_name": "Plaid Gold Checking","subtype": "checking","type": "depository"}],"numbers": {"ach": [{"account": "9900009606","account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D","routing": "011401533","wire_routing": "021000021"}],"eft": [{"account": "111122223333","account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D","institution": "021","branch": "01140"}],"international": [{"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D","bic": "NWBKGB21","iban": "GB29NWBK60161331926819"}],"bacs": [{"account": "31926819","account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D","sort_code": "601613"}]},"item": {"available_products": ["balance","identity","payment_initiation","transactions"],"billed_products": ["assets","auth"],"consent_expiration_time": null,"error": null,"institution_id": "ins_117650","item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6","update_type": "background","webhook": "https://www.genericwebhookurl.com/webhook"},"request_id": "m8MDnv9okwxFNBV"}
Balance
Verify real-time account balances.
| In this section | |
|---|---|
/accounts/balance/get | Fetch real-time account balances |
/accounts/balance/get
Retrieve real-time balance data
The /accounts/balance/get endpoint returns the real-time balance for each of an Item's accounts. While other endpoints may return a balance object, only /accounts/balance/get forces the available and current balance fields to be refreshed rather than cached. This endpoint can be used for existing Items that were added via any of Plaid’s other products. This endpoint can be used as long as Link has been initialized with any other product, balance itself is not a product that can be used to initialize Link.
Request fields and example
access_tokenrequiredstringThe access token associated with the Item data is being requested for. | ||
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | ||
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | ||
optionsobjectAn optional object to filter /accounts/balance/get results.
|
1
2
3
4
5
6
7
8
9
10
11
// Pull real-time balance information for each account associated// with the Itemconst request: AccountsGetRequest = {access_token: accessToken,};try {const response = await plaidClient.accountsBalanceGet(request);const accounts = response.data.accounts;} catch (error) {// handle error}
accounts/balance/get
Response fields and example
accounts[object]An array of financial institution accounts associated with the Item.
If /accounts/balance/get was called, each account will include real-time balance information.
| |||||||||||||||||
itemobjectMetadata about the Item.
| |||||||||||||||||
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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
{"accounts": [{"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp","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": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK","balances": {"available": null,"current": 410,"iso_currency_code": "USD","limit": 2000,"unofficial_currency_code": null},"mask": "3333","name": "Plaid Credit Card","official_name": "Plaid Diamond 12.5% APR Interest Credit Card","subtype": "credit card","type": "credit"},{"account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE","balances": {"available": null,"current": 65262,"iso_currency_code": "USD","limit": null,"unofficial_currency_code": null},"mask": "7777","name": "Plaid Student Loan","official_name": null,"subtype": "student","type": "loan"}],"item": {"available_products": ["balance","identity","investments"],"billed_products": ["assets","auth","liabilities","transactions"],"consent_expiration_time": null,"error": null,"institution_id": "ins_3","item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6","update_type": "background","webhook": "https://www.genericwebhookurl.com/webhook"},"request_id": "qk5Bxes3gDfv4F2"}
Identity
Verify the name, address, phone number, and email address of a user against bank account information on file.
| In this section | |
|---|---|
/identity/get | Fetch identity data |
/identity/get
Retrieve identity data
The /identity/get endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses. Only name data is guaranteed to be returned; other fields will be empty arrays if not provided by the institution.
Note: This request may take some time to complete if identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | |
access_tokenrequiredstringThe access token associated with the Item data is being requested for. | |
optionsobjectAn optional object to filter /identity/get results.
|
1
2
3
4
5
6
7
8
9
10
11
12
// Pull Identity data for an Itemconst request: IdentityGetRequest = {access_token: accessToken,};try {const response = await plaidClient.identityGet(request);const identities = response.data.accounts.flatMap((account) => account.owners,);} catch (error) {// handle error}
identity/get
Response fields and example
accounts[object]The accounts for which Identity data has been requested
| ||||||||||||||||||||||||||||||||
itemobjectMetadata about the Item.
| ||||||||||||||||||||||||||||||||
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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
{"accounts": [{"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp","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","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": "accountholder1@example.com","primary": false,"type": "secondary"},{"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": "1112224444","primary": false,"type": "work"},{"data": "1112225555","primary": false,"type": "mobile"}]}],"subtype": "checking","type": "depository"},{"account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr","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","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": "accountholder1@example.com","primary": false,"type": "secondary"},{"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": "1112224444","primary": false,"type": "work"},{"data": "1112225555","primary": false,"type": "mobile"}]}],"subtype": "savings","type": "depository"}],"item": {"available_products": ["balance","investments"],"billed_products": ["assets","auth","identity","liabilities","transactions"],"consent_expiration_time": null,"error": null,"institution_id": "ins_3","item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6","update_type": "background","webhook": "https://www.genericwebhookurl.com/webhook"},"request_id": "3nARps6TOYtbACO"}
Assets
Create, delete, retrieve and share Asset Reports with information about a user's assets and transactions.
| In this section | |
|---|---|
/asset_report/create | Create an Asset Report |
/asset_report/get | Get an Asset Report |
/asset_report/pdf/get | Get a PDF Asset Report |
/asset_report/refresh | Create an updated Asset Report |
/asset_report/filter | Filter unneeded accounts from an Asset Report |
/asset_report/remove | Delete an asset report |
/asset_report/audit_copy/create | Create an Audit Copy of an Asset Report for sharing |
/asset_report/audit_copy/remove | Delete an Audit Copy of an Asset Report |
/asset_report/create
Create an Asset Report
The /asset_report/create endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the asset_report_token return value to the /asset_report/get or /asset_report/pdf/get endpoints.
The Asset Report takes some time to be created and is not available immediately after calling /asset_report/create. When the Asset Report is ready to be retrieved using /asset_report/get or /asset_report/pdf/get, Plaid will fire a PRODUCT_READY webhook. For full details of the webhook schema, see Asset Report webhooks.
The /asset_report/create endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the /asset_report/refresh endpoint.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | ||||||||||
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | ||||||||||
access_tokensrequired[string]An array of access tokens corresponding to the Items that will be included in the report. The assets product must have been initialized for the Items during link; the Assets product cannot be added after initialization.Min items: 1 Max items: 99 | ||||||||||
days_requestedrequiredintegerThe maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, days_requested must be at least 61 for new originations or at least 31 for refinancings.Maximum: 731 Minimum: 0 | ||||||||||
optionsobjectAn optional object to filter /asset_report/create results. If provided, must be non-null. The optional user object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program.
|
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
const daysRequested = 60;const options = {client_report_id: '123',webhook: 'https://www.example.com',user: {client_user_id: '7f57eb3d2a9j6480121fx361',first_name: 'Jane',middle_name: 'Leah',last_name: 'Doe',ssn: '123-45-6789',phone_number: '(555) 123-4567',email: 'jane.doe@example.com',},};const request: AssetReportCreateRequest = {access_tokens: [accessToken],days_requested,options,};// 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.try {const response = await plaidClient.assetReportCreate(request);const assetReportId = response.data.asset_report_id;const assetReportToken = response.data.asset_report_token;} catch (error) {// handle error}
asset_report/create
Response fields and example
asset_report_tokenstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
asset_report_idstringA unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. |
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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"}
/asset_report/get
Retrieve an Asset Report
The /asset_report/get endpoint retrieves the Asset Report in JSON format. Before calling /asset_report/get, you must first create the Asset Report using /asset_report/create (or filter an Asset Report using /asset_report/filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid. You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report.
To retrieve an Asset Report with Insights, call the /asset_report/get endpoint with include_insights set to true.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_tokenrequiredstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
include_insightsbooleantrue if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted.Default: false |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const request: request = {asset_report_token: assetReportToken,include_insights: true,};try {const response = await plaidClient.assetReportGet(request);const assetReportId = response.data.asset_report_id;} catch (error) {if (error.data.error_code == 'PRODUCT_NOT_READY') {// Asset report is not ready yet. Try again later} else {// handle error}}
asset_report/get
Response fields and example
reportobjectAn object representing an Asset Report
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
warnings[object]If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
{"report": {"asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d","client_report_id": "123abc","date_generated": "2020-06-05T22:47:53Z","days_requested": 3,"items": [{"accounts": [{"account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr","balances": {"available": 200,"current": 210,"iso_currency_code": "USD","limit": null,"unofficial_currency_code": null},"days_available": 3,"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},{"current": 210,"date": "2020-06-02","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": "accountholder1@example.com","primary": false,"type": "secondary"},{"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": "1112224444","primary": false,"type": "work"},{"data": "1112225555","primary": false,"type": "mobile"}]}],"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": 3,"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": "accountholder1@example.com","primary": false,"type": "secondary"},{"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": "1112224444","primary": false,"type": "work"},{"data": "1112225555","primary": false,"type": "mobile"}]}],"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": 3,"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},{"current": 410,"date": "2020-06-02","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": "accountholder1@example.com","primary": false,"type": "secondary"},{"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": "1112224444","primary": false,"type": "work"},{"data": "1112225555","primary": false,"type": "mobile"}]}],"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": []}
/asset_report/pdf/get
Retrieve a PDF Asset Report
The /asset_report/pdf/get endpoint retrieves the Asset Report in PDF format. Before calling /asset_report/pdf/get, you must first create the Asset Report using /asset_report/create (or filter an Asset Report using /asset_report/filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
The response to /asset_report/pdf/get is the PDF binary data. The request_id is returned in the Plaid-Request-ID header.
View a sample PDF Asset Report.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_tokenrequiredstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
1
2
3
4
5
6
7
8
9
10
11
try {const request: AssetReportPDFGetRequest = {asset_report_token: assetReportToken,};const response = await plaidClient.assetReportPdfGet(request, {responseType: 'arraybuffer',});const pdf = response.buffer.toString('base64');} catch (error) {// handle error}
Response
This endpoint returns binary PDF data. View a sample Asset Report PDF.
/asset_report/refresh
Refresh an Asset Report
An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the /asset_report/refresh endpoint to create a new Asset Report based on the old one, but with the most recent data available.
The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to /asset_report/filter. By default, the new Asset Report will also use the same parameters you submitted with your original /asset_report/create request, but the original days_requested value and the values of any parameters in the options object can be overridden with new values. To change these arguments, simply supply new values for them in your request to /asset_report/refresh. Submit an empty string ("") for any previously-populated fields you would like set as empty.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | ||||||||||
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | ||||||||||
asset_report_tokenrequiredstringThe asset_report_token returned by the original call to /asset_report/create | ||||||||||
days_requestedintegerThe maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to /asset_report/create will be used.Minimum: 0 Maximum: 731 | ||||||||||
optionsobjectAn optional object to filter /asset_report/refresh results. If provided, cannot be null. If not specified, the options from the original call to /asset_report/create will be used.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const request: AssetReportRefreshRequest = {asset_report_token: assetReportToken,daysRequested: 60,options: {client_report_id: '123',webhook: 'https://www.example.com',user: {client_user_id: '7f57eb3d2a9j6480121fx361',first_name: 'Jane',middle_name: 'Leah',last_name: 'Doe',ssn: '123-45-6789',phone_number: '(555) 123-4567',email: 'jane.doe@example.com',},},};try {const response = await plaidClient.assetReportRefresh(request);const assetReportId = response.data.asset_report_id;} catch (error) {// handle error}
asset_report/refresh
Response fields and example
asset_report_idstringA unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. |
asset_report_tokenstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1
2
3
4
5
{"asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0","asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398","request_id": "NBZaq"}
/asset_report/filter
Filter Asset Report
By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the /accounts/get endpoint. To narrow an Asset Report to only a subset of accounts, use the /asset_report/filter endpoint.
To exclude certain Accounts from an Asset Report, first use the /asset_report/create endpoint to create the report, then send the asset_report_token along with a list of account_ids to exclude to the /asset_report/filter endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data.
Because Asset Reports are immutable, calling /asset_report/filter does not alter the original Asset Report in any way; rather, /asset_report/filter creates a new Asset Report with a new token and id. Asset Reports created via /asset_report/filter do not contain new Asset data, and are not billed.
Plaid will fire a PRODUCT_READY webhook once generation of the filtered Asset Report has completed.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_tokenrequiredstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
account_ids_to_excluderequired[string]The accounts to exclude from the Asset Report, identified by account_id. |
1
2
3
4
5
6
7
8
9
10
const request: AssetReportFilterRequest = {asset_report_token: assetReportToken,account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'],};try {const reponse = await plaidClient.assetReportFilter(request);const assetReportId = response.data.asset_report_id;} catch (error) {// handle error}
asset_report/filter
Response fields and example
asset_report_tokenstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
asset_report_idstringA unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. |
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1
2
3
4
5
{"asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c","asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9","request_id": "qEg07"}
/asset_report/remove
Delete an Asset Report
The /item/remove endpoint allows you to invalidate an access_token, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically.
The /asset_report/remove endpoint allows you to remove an Asset Report. Removing an Asset Report invalidates its asset_report_token, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does invalidate any audit_copy_tokens associated with the Asset Report.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_tokenrequiredstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
1
2
3
4
5
6
7
8
9
const request: AssetReportRemoveRequest = {asset_report_token: assetReportToken,};try {const response = await plaidClient.assetReportRemove(request);const removed = response.data.removed;} catch (error) {// handle error}
asset_report/remove
Response fields and example
removedbooleantrue if the Asset Report was successfully removed. |
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1
2
3
4
{"removed": true,"request_id": "I6zHN"}
/asset_report/audit_copy/create
Create Asset Report Audit Copy
Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can supply an Audit Copy directly to Fannie Mae on your behalf if you participate in the Day 1 Certainty™ program. An Audit Copy contains the same underlying data as the Asset Report.
To grant access to an Audit Copy, use the /asset_report/audit_copy/create endpoint to create an audit_copy_token and then pass that token to the third party who needs access. Each third party has its own auditor_id, for example fannie_mae. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_tokenrequiredstringA token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
auditor_idrequiredstringThe auditor_id of the third party with whom you would like to share the Asset Report. |
1
2
3
4
5
6
7
8
9
10
11
12
// The auditor ID corresponds to the third party with which you want to share// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.const request: AssetReportAuditCopyCreateRequest = {asset_report_token: createResponse.data.asset_report_token,auditor_id: 'fannie_mae',};try {const response = await plaidClient.assetReportAuditCopyCreate(request);const auditCopyToken = response.data.audit_copy_token;} catch (error) {// handle error}
asset_report/audit_copy/create
Response fields and example
audit_copy_tokenstringA token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely. |
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1
2
3
4
{"audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4","request_id": "Iam3b"}
/asset_report/audit_copy/remove
Remove Asset Report Audit Copy
The /asset_report/audit_copy/remove endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the audit_copy_token associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
audit_copy_tokenrequiredstringThe audit_copy_token granting access to the Audit Copy you would like to revoke. |
1
2
3
4
5
6
7
8
9
10
// auditCopyToken is the token from the createAuditCopy response.const request: AssetReportAuditCopyRemoveRequest = {audit_copy_token: auditCopyToken,};try {const response = await plaidClient.assetReportAuditCopyRemove(request);const removed = response.data.removed;} catch (error) {// handle error}
asset_report/audit_copy/remove
Response fields and example
removedbooleantrue if the Audit Copy was successfully removed. |
request_idstringA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1
2
3
4
{"removed": true,"request_id": "m8MDnv9okwxFNBV"}
Investments
| In this section | |
|---|---|
/investments/holdings/get | Fetch investment holdings |
/investments/transactions/get | Fetch investment transactions |
/investments/holdings/get
Get Investment holdings
The /investments/holdings/get endpoint allows developers to receive user-authorized stock position data for investment-type accounts.
Request fields and example
client_idstringYour Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | |
secretstringYour Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | |
access_tokenrequiredstringThe access token associated with the Item data is being requested for. | |
optionsobjectAn optional object to filter /investments/holdings/get results. If provided, must not be null.
|
1
2
3
4
5
6
7
8
9
10
11
// Pull Holdings for an Itemconst request: InvestmentsHoldingsGetRequest = {access_token: accessToken,};try {const response = await plaidClient.investmentsHoldingsGet(request);const holdings = response.data.holdings;const securities = response.data.securities;} catch (error) {// handle error}
investments/holdings/get
Response fields and example
accounts[object]The accounts associated with the Item
|