Skip to main content
The Plaid integration enables users to securely link their bank accounts and retrieve comprehensive financial data. All endpoints are prefixed with /api/plaid.

​
Authentication

Plaid requires the following environment variables:
  • PLAID_CLIENT_ID - Your Plaid client ID
  • PLAID_SECRET - Your Plaid secret key
  • PLAID_ENV - Environment: sandbox, development, or production
Create a Link token to initialize the Plaid Link frontend component. 
curl -X POST "http://localhost:3001/api/plaid/create-link-token" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123"}'
​
userId
string
required
Unique identifier for your user. Used to associate Plaid accounts with your users.
​
linkToken
string
Token used to initialize Plaid Link on the frontend. Valid for 4 hours.

​
Exchange Public Token

Exchange a public token (received from Plaid Link) for an access token. 
curl -X POST "http://localhost:3001/api/plaid/exchange-token" \
  -H "Content-Type: application/json" \
  -d '{
    "publicToken": "public-sandbox-abc123",
    "userId": "user_123"
  }'
​
publicToken
string
required
Public token received from Plaid Link after user completes authentication
​
userId
string
required
User identifier to associate the access token with
​
success
boolean
Whether the token exchange was successful. The access token is stored server-side.
In production, access tokens should be encrypted and stored securely in a database. The current implementation uses in-memory storage for demonstration.

​
Account Data

​
Get Accounts

Retrieve all linked accounts for a user with enhanced financial profile data. 
curl -X GET "http://localhost:3001/api/plaid/accounts/user_123"
​
depository
DepositoryAccount[]
Checking and savings accounts
​
depository[].id
string
Plaid account identifier
​
depository[].type
string
Account type: depository
​
depository[].subtype
string
Account subtype: checking, savings, etc.
​
depository[].name
string
Account name from institution
​
depository[].balance
number
Current balance in dollars
​
depository[].available
number
Available balance (may differ from current if holds exist)
​
credit
CreditAccount[]
Credit card accounts
​
credit[].utilization
number
Credit utilization ratio (balance / limit)
​
credit[].apr
number
Annual percentage rate
​
credit[].minimumPayment
number
Minimum payment due
​
loans
LoanAccount[]
Student loans, mortgages, and other loans
​
loans[].originalAmount
number
Original loan principal
​
loans[].interestRate
number
Annual interest rate percentage
​
loans[].monthlyPayment
number
Monthly payment amount
​
investments
InvestmentAccount[]
Investment and brokerage accounts
​
investments[].holdings
Holding[]
Individual securities held in the account
​
investments[].allocation
object
Asset allocation breakdown by category
​
income
IncomeProfile
Analyzed income profile from transaction history
​
income.monthlyAmount
number
Estimated monthly income
​
income.frequency
string
Payment frequency: weekly, biweekly, monthly, or irregular
​
income.stabilityScore
number
Income stability score (0-1, higher is more stable)
​
spending
SpendingProfile
Analyzed spending profile from transaction history
​
spending.byCategory
object
Monthly spending breakdown by category
​
spending.volatility
number
Spending volatility coefficient (0-1)
​
spending.fixedExpenses
number
Estimated monthly fixed/recurring expenses
​
spending.variableExpenses
number
Estimated monthly variable expenses
​
netWorth
number
Calculated net worth: (liquid + investments) - (credit debt + loan debt)

​
Get Financial Profile

Retrieve a financial profile formatted specifically for Monte Carlo simulation. 
curl -X GET "http://localhost:3001/api/plaid/financial-profile/user_123"
​
liquidAssets
number
Total liquid assets (checking + savings)
​
creditDebt
number
Total credit card debt
​
loanDebt
number
Total loan debt (student loans, mortgages, etc.)
​
monthlyLoanPayments
number
Total monthly loan payments
​
monthlyIncome
number
Estimated monthly income
​
monthlySpending
number
Average monthly spending
​
monthlyBills
number
Estimated monthly fixed/recurring bills
​
spendingByCategory
object
Spending breakdown by category for detailed analysis
​
spendingVolatility
number
Spending volatility coefficient used in simulation
​
investmentAllocation
object
Aggregated investment allocation across all investment accounts
Check if a user has linked accounts. 
curl -X GET "http://localhost:3001/api/plaid/status/user_123"
​
linked
boolean
Whether the user has successfully linked a bank account

​
Data Sources

Plaid retrieves data from the following sources:
  • Accounts - Real-time balance and account details
  • Transactions - Last 90 days of transaction history
  • Liabilities - Credit card, student loan, and mortgage details (optional product)
  • Investments - Holdings and securities data (optional product)

​
Income & Spending Analysis

The API automatically analyzes transaction data to extract:

​
Income Detection

  • Identifies recurring salary deposits
  • Detects payment frequency (weekly, biweekly, monthly)
  • Calculates income stability score
  • Estimates monthly income

​
Spending Analysis

  • Categorizes all expenses
  • Separates fixed vs. variable expenses
  • Calculates spending volatility
  • Identifies recurring bills

​
Error Handling

{
  "error": "publicToken and userId are required"
}

​
Security Notes

The current implementation stores access tokens in-memory for demonstration purposes. In production:
  • Encrypt access tokens before storage
  • Store tokens in a secure database
  • Implement token rotation
  • Use webhook notifications for account updates
  • Follow Plaid’s security best practices

​
Plaid Environments

  • Sandbox - Testing with synthetic data (no real credentials)
  • Development - Testing with real credentials (free for development)
  • Production - Live environment (requires Plaid approval)
Set the environment using the PLAID_ENV environment variable.

Build docs developers (and LLMs) love

Get started for freeTalk to us