Aggregation API Reference

Plaid Exchange Data Aggregation 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.

Get Account and Identity Endpoint

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.

Get Transactions Endpoint

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
user_id
string
Opaque user identifier.
In: path
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
In: query
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
In: query
start_date
string
Oldest posting date from which to start returning transactions. If not provided, default to 30 days ago.

Format: date
In: query
end_date
string
Most recent posting date for which transactions may be included. If not provided, default to the current date.

Format: date
In: query

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. Either offset or total can be used when paging. If both are used, total will be used instead of offset.

total
integer
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
offset
string
A cursor string that represents the next page of transactions. Sending a blank offset will indicate the final page.
Initial call will be a 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}