Plaid Integration (/api/v1/plaid)

Connect financial institutions via Plaid. All endpoints require authentication via X-API-Key.

---

1. Create Link Token

Generate a Plaid Link token to initialize the Link flow for connecting a bank account.

• Method: POST
• Endpoint: /api/v1/plaid/link

Request Body (optional)

{
  "itemId": "uuid",       // Optional: for update-mode (re-authenticate existing item)
  "products": ["auth", "transactions"] // Optional: override default products
}

Response

{ "linkToken": "link-sandbox-..." }

---

2. Exchange Public Token

Exchange the public token from Plaid Link for an access token and store the connection.

• Method: POST
• Endpoint: /api/v1/plaid/exchange_public_token

Request Body

{ "publicToken": "public-sandbox-..." }

Response

{
  "itemId": "uuid",
  "institutionName": "Chase Bank",
  "products": ["auth", "transactions", "identity"]
}

---

3. List Plaid Items

List all connected bank accounts for the user.

• Method: GET
• Endpoint: /api/v1/plaid/items

Response

{
  "items": [
    {
      "id": "uuid",
      "institutionId": "ins_123",
      "institutionName": "Chase Bank",
      "products": ["auth", "transactions"],
      "status": "ACTIVE",
      "lastWebhookAt": null,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

---

4. Remove a Plaid Item

Disconnect a bank account.

• Method: DELETE
• Endpoint: /api/v1/plaid/items/:itemId

Response

{ "message": "Bank connection removed" }

---

5. Get Accounts

Retrieve account details for a connected Plaid item.

• Method: GET
• Endpoint: /api/v1/plaid/accounts
• Query: itemId (optional — uses latest active item if omitted)

---

6. Get Balances

Get current and available balances.

• Method: GET
• Endpoint: /api/v1/plaid/balance

---

7. Get Transactions

Retrieve transaction data within a date range.

• Method: GET
• Endpoint: /api/v1/plaid/transactions

Query Parameters

Parameter	Type	Default	Description
itemId	String	Latest active	Plaid item ID
startDate	String	30 days ago	Start date (YYYY-MM-DD)
endDate	String	Today	End date (YYYY-MM-DD)
count	Number	100	Number of transactions
offset	Number	0	Pagination offset

---

8. Sync Transactions

Incrementally sync new, modified, and removed transactions using Plaid's cursor-based sync.

• Method: GET
• Endpoint: /api/v1/plaid/transactions/sync

Response

{
  "added": [...],
  "modified": [...],
  "removed": [...],
  "cursor": "next-cursor-string"
}

---

9. Get Recurring Transactions

Identify recurring inflow and outflow streams.

• Method: GET
• Endpoint: /api/v1/plaid/transactions/recurring

Response

{
  "inflow_streams": [...],
  "outflow_streams": [...]
}

---

10. Get Identity

Retrieve verified identity data (names, addresses, emails, phone numbers) from the connected bank.

• Method: GET
• Endpoint: /api/v1/plaid/identity

---

11. Get Liabilities

Retrieve liabilities (credit cards, student loans, mortgages) from the connected bank.

• Method: GET
• Endpoint: /api/v1/plaid/liabilities

---

12. Get Investments

Retrieve investment holdings and securities.

• Method: GET
• Endpoint: /api/v1/plaid/investments

---

13. Get Investment Transactions

Retrieve investment transaction history.

• Method: GET
• Endpoint: /api/v1/plaid/investments/transactions

---

14. Get Item Info

Retrieve Plaid Item and institution information.

• Method: GET
• Endpoint: /api/v1/plaid/item

---

15. Get Income

Retrieve income verification data (paystubs).

• Method: GET
• Endpoint: /api/v1/plaid/income

---

16. List Statements

List available statements for a connected item.

• Method: GET
• Endpoint: /api/v1/plaid/statements

---

17. Download Statement

Download a specific statement as PDF.

• Method: GET
• Endpoint: /api/v1/plaid/statements/:statementId/download

---

18. Asset Reports

Create and fetch asset reports.

Action	Method	Endpoint
Create asset report	POST	/api/v1/plaid/assets/report
Get asset report	GET	/api/v1/plaid/assets/report

---

19. User Plaid Data

Get a summary of all connected bank items for the user.

• Method: GET
• Endpoint: /api/v1/plaid/user-data

Response

{
  "userId": "uuid",
  "items": [
    { "id": "uuid", "institutionName": "Chase Bank", "status": "ACTIVE" }
  ]
}

---

20. Auth

Get account and routing numbers for ACH transfers.

• Method: POST
• Endpoint: /api/v1/plaid/auth

---

21. Get Categories

Retrieve the full list of Plaid transaction categories.

• Method: GET
• Endpoint: /api/v1/plaid/categories

---

22. Sandbox Public Token (Development Only)

Create a sandbox public token for testing. Not available in production.

• Method: POST
• Endpoint: /api/v1/plaid/sandbox/public_token

Request Body

{
  "institutionId": "ins_109508",
  "products": ["auth", "transactions"]
}

Response

{ "publicToken": "public-sandbox-..." }