Aggregation API Reference

This API enables Plaid to make recurrent, user-absent requests in order to maintain a current and consistent view of a user’s permissioned accounts.

Retrieval API methods

User identity and accounts

GET /users/{user_id}

Provide user and account information for a given user ID. This endpoint contains the information necessary for the partner to support the Identity and Auth products.

Responses
200 OK

The request is authorized.

UserAccountInfoResponse

Basic account and identity enumeration.

identities
requiredarray
List of Identity instances necessary to fully resolve all records in accounts.

Min items: 1
user_identity_id
requiredstring
Indicate the Identity corresponding to the currently logged-in user.
securities
requiredarray
List of Securities necessary to fully resolve all records in accounts.

Min items: 0
accounts
requiredarray
List of all accounts for which this user is an owner or interested non-owner.
1{
2  "user_identity_id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
3  "identities": [
4    {
5      "id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
6      "name": "Jane Doe",
7      "email": "jane@plaid.com"
8    }
9  ],
10  "accounts": [
11    {
12      "id": "account_5921",
13      "isin": "US17275R1023",
14      "name": "CISCO SYSTEMS INC",
15      "symbol": "CSCO",
16      "is_cash_equivalent": true,
17      "current_price": "100.95",
18      "current_as_of": "2018-08-28",
19      "close_price": "100.95",
20      "type": "cash",
21      "currency": "USD",
22      "non_iso_currency": null
23    }
24  ],
25  "securities": [
26    {
27      "id": "R13oiR6lC5jNC5jK",
28      "last_activity_at": "2018-08-28",
29      "ownership_type": "individual",
30      "owner_identity_ids": [
31        "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
32      ],
33      "non_owner_identity_ids": null,
34      "status": "active",
35      "type": "depository",
36      "subtype": "cash management",
37      "name": "Vacation Money",
38      "official_name": "Pro Checking",
39      "display_mask": "9833",
40      "opening_date": "2018-08-28",
41      "current_balance": "100.95",
42      "available_balance": "100.95",
43      "tax_advantaged": true,
44      "currency": "USD",
45      "non_iso_currency": null
46    }
47  ]
48}

Privacy Implications of Per-User Request Model

Plaid’s privacy guarantee to end users is that it will never share per-account data, including knowledge of the existence of individual accounts, with applications unless the user has affirmatively indicated those accounts and applications should be linked. Plaid also will also minimize the storage details of accounts retrieved through this API which are not linked to any applications.

At times, it is necessary to communicate information about accounts not connected to any Plaid-powered applications, primarily for the purpose of enabling sensible UX, e.g. when drawing account selection screens. To ease implementation, this API operates at a per-user granularity and not a per-account granularity, because Plaid assumes the responsibility of providing a privacy-conscious view of the user’s accounts to each application.

However, Plaid provides the NotionalAccount and BasicIdentity models to enable implementers, if desired, to mask the existence of identities and accounts it knows are not linked to any Plaid applications. The partner is expected to use the Authorization API to ensure its access policy is synchronized with that of Plaid’s, i.e. both Plaid and the partner see the same items. Failure to do so will result in an inconsistent state and degraded end-user experiences.

304 Not Changed

If present, Plaid will consume the ETag header, and then present the most-recently seen ETag using the If-None-Match header on subsequent requests. If there has been no activity on, and no change to, the customer’s account, the partner may return 304 Not Changed with an empty HTTP body. Plaid will end the session and send no more requests until the next scheduled update.

It is recommended to generate ETags by concatenating and hashing the account_ids and last_activity_at timestamps for all accounts present in the response. If any identity data has changed, the ETag should always be new.

Retrieve transactions

GET /users/{user_id}/transactions

Provides a query interface for a user’s transactions across all accounts, optionally filtered by posting date.

Parameters

Retrieve user transactions.

Provides a query interface for a user’s transactions across all accounts, optionally filtered by posting date.

users/{user_id}/transactions

Request fields and example

start
integer
The offset from the beginning of the result set. For example, if start is set to 500, the results set will start with the 501st transaction. (If this parameter is not provided, the results set will start with the 1st transaction by default.)

Default: 0
limit
integer
The number of transactions to return in a given results set. For example, if limit is set to 10, the response will be limited to 10 transactions. (If this parameter is not provided, the results set to include up to 500 transactions by default.)

Default: 500
start_date
datetime
Oldest posting date from which to start returning transactions.

Default: (30 days ago)
end_date
datetime
Most recent posting date for which transactions may be included.

Default: (today)

Note

When considering whether a pending transaction (one which has not yet posted) should be included in a TransactionsResponse, evaluate whether the transaction date (transacted_at) falls within the range.

Responses
200 OK

The request was authorized and well-formed.

TransactionsResponse

Successful response to Transactions request.

total
requiredinteger
The number of transactions matching the request. This must count the total number of transactions matching the query, not just the length of this response.
A natural number, i.e. a non-negative integer.

Minimum: 0
transactions
requiredarray
Sequence of BaseTransaction subclass instances, across all accounts, matching the query.
1{
2  "total": 1,
3  "transactions": [
4    {
5      "type": "transfer",
6      "pending": false,
7      "amount": "250",
8      "fee_amount": "0",
9      "reward_amount": "0",
10      "reward_rate": "0",
11      "transfer_account_id": "3AP9Lwoo3s30E",
12      "method": "eft",
13      "id": "6AOU0jwFQw3sMZJ",
14      "account_id": "account1234",
15      "description": "Finance Charge",
16      "memo": "Transfer to Checking",
17      "category": null,
18      "tags": null,
19      "ending_balance": "1820.95",
20      "transacted_at": "2019-08-24T14:15:22Z",
21      "settled_at": "2019-08-25T08:15:42Z",
22      "spender_identity_id": "uid_1234",
23      "merchant_identity_id": null,
24      "geolocation": {
25        "coordinates": {
26          "lat": 40.7128,
27          "lon": 74.006
28        },
29        "city": "New York",
30        "region": "US-NY",
31        "country": "US"
32      },
33      "reward_currency": "USD",
34      "reward_non_iso_currency": null,
35      "currency": "USD",
36      "non_iso_currency": null
37    }
38  ]
39}