{"openapi":"3.0.3","info":{"title":"Finta API","version":"1.0.0","description":"API for accessing Finta financial data including bank connections, accounts, and transactions."},"servers":[{"url":"https://api.finta.io/v1","description":"Production server"}],"paths":{"/health":{"get":{"summary":"Health Check","description":"Returns the health status of the API. This endpoint is public and does not require authentication. Used for monitoring and uptime checks.","operationId":"getHealth","tags":["Health"],"security":[],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"ok":{"summary":"All services healthy","value":{"data":{"status":"ok","timestamp":"2024-03-15T10:30:00.000Z"}}},"degraded":{"summary":"Some non-critical services unavailable","value":{"data":{"status":"degraded","timestamp":"2024-03-15T10:30:00.000Z"}}}}}},"headers":{"x-request-id":{"description":"Unique request identifier for tracing","schema":{"type":"string","format":"uuid"}}}},"503":{"description":"Service unavailable - critical services are down","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"SERVICE_UNAVAILABLE","message":"Database is unavailable"}}}}}}}},"/accounts":{"get":{"summary":"List Accounts","description":"Returns all accounts with current balances for the authenticated user, aggregating data from all connected providers (Plaid, GoCardless, Stripe, Mercury).","operationId":"listAccounts","tags":["Accounts"],"parameters":[{"name":"connectionId","in":"query","description":"Filter accounts by bank connection ID","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of accounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsListResponse"},"example":{"data":[{"id":"acct_123","bankConnectionId":"550e8400-e29b-41d4-a716-446655440000","name":"Chase Checking","balance":{"current":5250,"available":5250,"limit":null,"interestRate":null},"currency":"USD","mask":"4567","type":"depository","subtype":"checking","provider":"Plaid","payment":null,"loanOrigination":null},{"id":"acct_456","bankConnectionId":"550e8400-e29b-41d4-a716-446655440001","name":"Chase Credit Card","balance":{"current":1250.75,"available":8749.25,"limit":10000,"interestRate":0.2499},"currency":"USD","mask":"1234","type":"credit","subtype":"credit card","provider":"Plaid","payment":{"lastPaymentAmount":500,"lastPaymentDate":"2024-03-01","nextPaymentDueDate":"2024-04-01","lastStatementBalance":1750.75,"minimumPaymentAmount":35,"nextMonthlyPayment":null},"loanOrigination":null}],"meta":{"count":2,"totalCount":2,"hasMore":false}}}},"headers":{"x-request-id":{"description":"Unique request identifier for tracing","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Rate limit ceiling for this endpoint","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}}}},"401":{"description":"Unauthorized - missing, invalid, disabled or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Invalid API key","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"403":{"description":"API access requires active pro subscription or trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"API access requires active pro subscription or trial","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"429":{"description":"Rate limit exceeded - retry after the `retryAfter` timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Rate limit exceeded","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f","retryAfter":1768766400000}}}},"500":{"description":"Internal server error. Failures during authentication return MiddlewareErrorResponse; failures inside the endpoint return ErrorResponse.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/MiddlewareErrorResponse"}]},"example":{"error":{"code":"INTERNAL_ERROR","message":"Internal server error"}}}}}}}},"/bank-connections":{"get":{"summary":"List Bank Connections","description":"Returns all bank connections for the authenticated user, including connections from all supported providers (Plaid, GoCardless, Stripe, Mercury).","operationId":"listBankConnections","tags":["Bank Connections"],"responses":{"200":{"description":"List of bank connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankConnectionsListResponse"},"example":{"bank_connections":[{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Chase Checking","provider":"Plaid","error":null},{"id":"550e8400-e29b-41d4-a716-446655440001","name":"Mercury Business","provider":"Mercury","error":null}],"meta":{"count":2,"totalCount":2,"hasMore":false}}}},"headers":{"x-request-id":{"description":"Unique request identifier for tracing","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Rate limit ceiling for this endpoint","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}}}},"401":{"description":"Unauthorized - missing, invalid, disabled or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Invalid API key","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"403":{"description":"API access requires active pro subscription or trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"API access requires active pro subscription or trial","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"429":{"description":"Rate limit exceeded - retry after the `retryAfter` timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Rate limit exceeded","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f","retryAfter":1768766400000}}}},"500":{"description":"Internal server error. Failures during authentication return MiddlewareErrorResponse; failures inside the endpoint return ErrorResponse.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/MiddlewareErrorResponse"}]},"example":{"error":{"code":"INTERNAL_ERROR","message":"Internal server error"}}}}}}}},"/transactions":{"get":{"summary":"List Transactions","description":"Returns transactions for a specific bank connection with filtering and pagination. Categories are returned using the v2 categorization system.","operationId":"listTransactions","tags":["Transactions"],"parameters":[{"name":"bankConnectionId","in":"query","description":"The bank connection ID to fetch transactions from","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"accountIds","in":"query","description":"Comma-separated list of account IDs to filter transactions. If not provided, transactions from all accounts in the connection are returned.","required":false,"schema":{"type":"string"},"example":"acct_123,acct_456"},{"name":"startDate","in":"query","description":"Filter transactions on or after this date (ISO 8601 format, e.g., 2024-01-01)","required":true,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"Filter transactions on or before this date (ISO 8601 format, e.g., 2024-03-31)","required":true,"schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Maximum number of transactions per page (default: 50, max: 250)","required":false,"schema":{"type":"integer","minimum":1,"maximum":250,"default":50}},{"name":"cursor","in":"query","description":"Pagination cursor from the previous response's nextPage URL. For Stripe connections, this is a transaction ID. For Plaid/Mercury/GoCardless, this is a numeric offset.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of transactions with categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsListResponse"},"example":{"data":{"transactions":[{"id":"txn_abc123","summary":"UBER TRIP","createdAt":"2024-03-15T14:30:00.000Z","postedAt":"2024-03-16T00:00:00.000Z","amount":-25.5,"currency":"USD","isPending":false,"subAccount":null,"merchantName":"Uber","categoryId":"22012000","fees":null,"feeType":null,"netAmount":null,"source":null,"type":null,"provider":"Plaid","accountId":"acct_123"},{"id":"txn_def456","summary":"DIRECT DEPOSIT","createdAt":"2024-03-14T09:00:00.000Z","postedAt":null,"amount":3500,"currency":"USD","isPending":true,"subAccount":null,"merchantName":null,"categoryId":null,"fees":null,"feeType":null,"netAmount":null,"source":null,"type":null,"provider":"Plaid","accountId":"acct_123"}],"categories":[{"id":"22012000","name":"Taxi","group":"TRANSPORTATION","description":"Taxi and rideshare services"}]},"meta":{"count":2,"nextPage":"https://api.finta.io/v1/transactions?bankConnectionId=550e8400-e29b-41d4-a716-446655440000&startDate=2024-01-01&endDate=2024-03-31&limit=50&cursor=50"}}}},"headers":{"x-request-id":{"description":"Unique request identifier for tracing","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Rate limit ceiling for this endpoint (50/hour)","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}}}},"400":{"description":"Bad request - Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingBankConnectionId":{"summary":"Missing bankConnectionId","value":{"error":{"code":"BAD_REQUEST","message":"bankConnectionId: bankConnectionId is required"}}},"invalidBankConnectionId":{"summary":"Invalid bankConnectionId format","value":{"error":{"code":"BAD_REQUEST","message":"bankConnectionId: bankConnectionId must be a valid UUID"}}},"invalidLimit":{"summary":"Invalid limit","value":{"error":{"code":"BAD_REQUEST","message":"limit: limit cannot exceed 250"}}}}}}},"401":{"description":"Unauthorized - missing, invalid, disabled or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Invalid API key","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"403":{"description":"API access requires active pro subscription or trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"API access requires active pro subscription or trial","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"404":{"description":"Bank connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"NOT_FOUND","message":"Bank connection not found"}}}}},"429":{"description":"Rate limit exceeded - retry after the `retryAfter` timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Rate limit exceeded","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f","retryAfter":1768766400000}}}},"500":{"description":"Internal server error. Failures during authentication return MiddlewareErrorResponse; failures inside the endpoint return ErrorResponse.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/MiddlewareErrorResponse"}]},"example":{"error":{"code":"INTERNAL_ERROR","message":"Internal server error"}}}}}}}},"/holdings":{"get":{"summary":"List Holdings","description":"Returns investment holdings for a specific bank connection. Holdings include stocks, bonds, ETFs, and other securities. Currently only available for Plaid connections with the Investments product enabled.","operationId":"listHoldings","tags":["Holdings"],"parameters":[{"name":"bankConnectionId","in":"query","description":"The bank connection ID to fetch holdings from","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"accountIds","in":"query","description":"Comma-separated list of account IDs to filter holdings. If not provided, holdings from all accounts in the connection are returned.","required":false,"schema":{"type":"string"},"example":"acct_123,acct_456"},{"name":"limit","in":"query","description":"Maximum number of holdings per page (default: 100, max: 250)","required":false,"schema":{"type":"integer","minimum":1,"maximum":250,"default":100}},{"name":"cursor","in":"query","description":"Pagination cursor (numeric offset) from the previous response's nextPage URL.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of holdings with securities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HoldingsListResponse"},"example":{"data":{"holdings":[{"id":"acct_123:sec_aapl","accountId":"acct_123","securityId":"sec_aapl","quantity":10.5,"costBasis":1575,"institutionPrice":175.25,"institutionValue":1840.125,"currency":"USD","priceAsOf":"2024-03-15","provider":"Plaid"},{"id":"acct_123:sec_vti","accountId":"acct_123","securityId":"sec_vti","quantity":25,"costBasis":5000,"institutionPrice":220.5,"institutionValue":5512.5,"currency":"USD","priceAsOf":"2024-03-15","provider":"Plaid"}],"securities":[{"id":"sec_aapl","symbol":"AAPL","name":"Apple Inc.","type":"equity"},{"id":"sec_vti","symbol":"VTI","name":"Vanguard Total Stock Market ETF","type":"etf"}]},"meta":{"count":2,"totalCount":2,"hasMore":false,"nextPage":null}}}},"headers":{"x-request-id":{"description":"Unique request identifier for tracing","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Rate limit ceiling for this endpoint (50/hour)","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}}}},"400":{"description":"Bad request - Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingBankConnectionId":{"summary":"Missing bankConnectionId","value":{"error":{"code":"BAD_REQUEST","message":"bankConnectionId: bankConnectionId is required"}}},"invalidBankConnectionId":{"summary":"Invalid bankConnectionId format","value":{"error":{"code":"BAD_REQUEST","message":"bankConnectionId: bankConnectionId must be a valid UUID"}}},"invalidLimit":{"summary":"Invalid limit","value":{"error":{"code":"BAD_REQUEST","message":"limit: limit cannot exceed 250"}}}}}}},"401":{"description":"Unauthorized - missing, invalid, disabled or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Invalid API key","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"403":{"description":"API access requires active pro subscription or trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"API access requires active pro subscription or trial","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"404":{"description":"Bank connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"NOT_FOUND","message":"Bank connection not found"}}}}},"429":{"description":"Rate limit exceeded - retry after the `retryAfter` timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Rate limit exceeded","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f","retryAfter":1768766400000}}}},"500":{"description":"Internal server error. Failures during authentication return MiddlewareErrorResponse; failures inside the endpoint return ErrorResponse.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/MiddlewareErrorResponse"}]},"example":{"error":{"code":"INTERNAL_ERROR","message":"Internal server error"}}}}},"502":{"description":"Provider service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PROVIDER_SERVICE_UNAVAILABLE","message":"Provider service is unavailable"}}}}}}}},"/investment-transactions":{"get":{"summary":"List Investment Transactions","description":"Returns investment transactions (buys, sells, dividends, etc.) for a specific bank connection. Currently only available for Plaid connections with the Investments product enabled.","operationId":"listInvestmentTransactions","tags":["Investment Transactions"],"parameters":[{"name":"bankConnectionId","in":"query","description":"The bank connection ID to fetch investment transactions from","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"accountIds","in":"query","description":"Comma-separated list of account IDs to filter transactions. If not provided, transactions from all accounts in the connection are returned.","required":false,"schema":{"type":"string"},"example":"acct_123,acct_456"},{"name":"startDate","in":"query","description":"Start date for transactions in YYYY-MM-DD format. Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date"},"example":"2024-01-01"},{"name":"endDate","in":"query","description":"End date for transactions in YYYY-MM-DD format. Defaults to today.","required":false,"schema":{"type":"string","format":"date"},"example":"2024-03-31"},{"name":"limit","in":"query","description":"Maximum number of transactions per page (default: 100, max: 250)","required":false,"schema":{"type":"integer","minimum":1,"maximum":250,"default":100}},{"name":"cursor","in":"query","description":"Pagination cursor (numeric offset) from the previous response's nextPage URL.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of investment transactions with securities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestmentTransactionsListResponse"},"example":{"data":{"investmentTransactions":[{"id":"inv_txn_123","accountId":"acct_123","securityId":"sec_aapl","type":"buy","subtype":"trade","date":"2024-03-15","quantity":5,"price":185.5,"amount":927.5,"fees":0,"currency":"USD","description":"Buy 5 shares AAPL","provider":"Plaid"},{"id":"inv_txn_124","accountId":"acct_123","securityId":"sec_vti","type":"cash","subtype":"dividend","date":"2024-03-10","quantity":0,"price":0,"amount":25.5,"fees":0,"currency":"USD","description":"Cash dividend VTI","provider":"Plaid"}],"securities":[{"id":"sec_aapl","symbol":"AAPL","name":"Apple Inc.","type":"equity"},{"id":"sec_vti","symbol":"VTI","name":"Vanguard Total Stock Market ETF","type":"etf"}]},"meta":{"count":2,"totalCount":50,"hasMore":true,"nextPage":"https://api.finta.io/v1/investment-transactions?bankConnectionId=abc&startDate=2024-01-01&endDate=2024-03-31&limit=100&cursor=2"}}}},"headers":{"x-request-id":{"description":"Unique request identifier for tracing","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Rate limit ceiling for this endpoint (50/hour)","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}}}},"400":{"description":"Bad request - Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingBankConnectionId":{"summary":"Missing bankConnectionId","value":{"error":{"code":"BAD_REQUEST","message":"bankConnectionId: bankConnectionId is required"}}},"invalidBankConnectionId":{"summary":"Invalid bankConnectionId format","value":{"error":{"code":"BAD_REQUEST","message":"bankConnectionId: bankConnectionId must be a valid UUID"}}},"invalidDateFormat":{"summary":"Invalid date format","value":{"error":{"code":"BAD_REQUEST","message":"startDate: startDate must be in YYYY-MM-DD format"}}},"invalidLimit":{"summary":"Invalid limit","value":{"error":{"code":"BAD_REQUEST","message":"limit: limit cannot exceed 250"}}}}}}},"401":{"description":"Unauthorized - missing, invalid, disabled or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Invalid API key","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"403":{"description":"API access requires active pro subscription or trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"API access requires active pro subscription or trial","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f"}}}},"404":{"description":"Bank connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"NOT_FOUND","message":"Bank connection not found"}}}}},"429":{"description":"Rate limit exceeded - retry after the `retryAfter` timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareErrorResponse"},"example":{"error":"Rate limit exceeded","requestId":"4f3c2a1e-8b7d-4c6a-9e5f-1a2b3c4d5e6f","retryAfter":1768766400000}}}},"500":{"description":"Internal server error. Failures during authentication return MiddlewareErrorResponse; failures inside the endpoint return ErrorResponse.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/MiddlewareErrorResponse"}]},"example":{"error":{"code":"INTERNAL_ERROR","message":"Internal server error"}}}}},"502":{"description":"Provider service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"PROVIDER_SERVICE_UNAVAILABLE","message":"Provider service is unavailable"}}}}}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["status","timestamp"],"properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"'ok' when all services are healthy, 'degraded' when non-critical services are unavailable"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the health check"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"MiddlewareErrorResponse":{"type":"object","description":"Returned by API key authentication, rate limiting and the subscription check, before the endpoint runs. `error` is one of: \"Missing or invalid Authorization header\", \"Invalid API key\", \"API key has been disabled\", \"API key has expired\" (401); \"API access requires active pro subscription or trial\" (403); \"Rate limit exceeded\" (429, with `retryAfter`); \"Internal error\" (500).","required":["error","requestId"],"properties":{"error":{"type":"string","description":"Human-readable error message","example":"Invalid API key"},"requestId":{"type":"string","description":"Request ID, also sent in the `x-request-id` response header"},"retryAfter":{"type":"integer","format":"int64","description":"Only on 429. Unix timestamp in milliseconds when the rate limit resets and requests can be retried","example":1768766400000}}},"BankConnection":{"type":"object","required":["id","name","provider","error"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the bank connection"},"name":{"type":"string","description":"Display name of the bank connection (institution name)"},"provider":{"type":"string","enum":["Plaid","GoCardless","Stripe","Mercury"],"description":"The data provider for this connection"},"error":{"type":"string","nullable":true,"description":"Error code if the connection requires attention (e.g., ITEM_LOGIN_REQUIRED for Plaid)"}}},"BankConnectionsListResponse":{"type":"object","required":["bank_connections","meta"],"properties":{"bank_connections":{"type":"array","items":{"$ref":"#/components/schemas/BankConnection"},"description":"List of bank connections"},"meta":{"type":"object","required":["count","totalCount","hasMore"],"properties":{"count":{"type":"integer","description":"Number of connections in this response"},"totalCount":{"type":"integer","description":"Total number of connections available"},"hasMore":{"type":"boolean","description":"Whether more results are available (always false, no pagination)"}}}}},"Balance":{"type":"object","required":["current","available","limit","interestRate"],"properties":{"current":{"type":"number","nullable":true,"description":"Current balance of the account"},"available":{"type":"number","nullable":true,"description":"Available balance (for depository accounts, amount available to spend; for credit accounts, available credit)"},"limit":{"type":"number","nullable":true,"description":"Credit limit (for credit accounts only)"},"interestRate":{"type":"number","nullable":true,"description":"Interest rate as a decimal (e.g., 0.2499 for 24.99%)"}}},"PaymentInfo":{"type":"object","required":["lastPaymentAmount","lastPaymentDate","nextPaymentDueDate","lastStatementBalance","minimumPaymentAmount","nextMonthlyPayment"],"properties":{"lastPaymentAmount":{"type":"number","nullable":true,"description":"Amount of the last payment made"},"lastPaymentDate":{"type":"string","nullable":true,"format":"date","description":"Date of the last payment (ISO 8601 date)"},"nextPaymentDueDate":{"type":"string","nullable":true,"format":"date","description":"Next payment due date (ISO 8601 date)"},"lastStatementBalance":{"type":"number","nullable":true,"description":"Balance of the last statement"},"minimumPaymentAmount":{"type":"number","nullable":true,"description":"Minimum payment amount due"},"nextMonthlyPayment":{"type":"number","nullable":true,"description":"Next monthly payment amount (for loans/mortgages)"}}},"LoanOriginationInfo":{"type":"object","required":["originationDate","originationPrincipalAmount"],"properties":{"originationDate":{"type":"string","nullable":true,"format":"date","description":"Date the loan was originated (ISO 8601 date)"},"originationPrincipalAmount":{"type":"number","nullable":true,"description":"Original principal amount of the loan"}}},"Account":{"type":"object","required":["id","bankConnectionId","name","balance","currency","mask","type","subtype","provider","payment","loanOrigination"],"properties":{"id":{"type":"string","description":"Unique identifier for the account from the provider"},"bankConnectionId":{"type":"string","format":"uuid","description":"ID of the bank connection this account belongs to"},"name":{"type":"string","description":"Name of the account (e.g., 'Chase Checking')"},"balance":{"$ref":"#/components/schemas/Balance"},"currency":{"type":"string","nullable":true,"description":"Currency code (e.g., 'USD', 'EUR')"},"mask":{"type":"string","nullable":true,"description":"Last 4 digits or masked account number"},"type":{"type":"string","enum":["depository","credit","investment","loan","payment","other"],"description":"Account type (depository, credit, investment, loan, payment, other)"},"subtype":{"type":"string","nullable":true,"description":"Account subtype (checking, savings, credit card, mortgage, etc.)"},"provider":{"type":"string","enum":["Plaid","GoCardless","Stripe","Mercury"],"description":"The data provider for this account"},"payment":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PaymentInfo"}],"description":"Payment information (for credit cards, loans, mortgages). Null if not applicable."},"loanOrigination":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/LoanOriginationInfo"}],"description":"Loan origination information (for loans, mortgages). Null if not applicable."}}},"AccountsListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Account"},"description":"List of accounts"},"meta":{"type":"object","required":["count","totalCount","hasMore"],"properties":{"count":{"type":"integer","description":"Number of accounts in this response"},"totalCount":{"type":"integer","description":"Total number of accounts available"},"hasMore":{"type":"boolean","description":"Whether more results are available (always false, no pagination)"}}}}},"Transaction":{"type":"object","required":["id","summary","createdAt","postedAt","amount","currency","isPending","subAccount","merchantName","categoryId","fees","feeType","netAmount","source","type","provider","accountId"],"properties":{"id":{"type":"string","description":"Unique identifier for the transaction. For pending transactions that become posted, this ID remains stable (uses pendingTransactionId when available)."},"summary":{"type":"string","description":"Transaction description/name"},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the transaction was created"},"postedAt":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601 timestamp when the transaction was posted. Null if the transaction is pending."},"amount":{"type":"number","description":"Transaction amount. Negative values indicate debits/expenses, positive values indicate credits/income."},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency code (e.g., 'USD', 'EUR')"},"isPending":{"type":"boolean","description":"Whether the transaction is still pending (not yet posted)"},"subAccount":{"type":"string","nullable":true,"description":"Sub-account identifier if applicable"},"merchantName":{"type":"string","nullable":true,"description":"Name of the merchant or counterparty"},"categoryId":{"type":"string","nullable":true,"description":"Category ID (v2 categorization). Can be used to look up the category in the categories array."},"fees":{"type":"number","nullable":true,"description":"Total fees associated with the transaction"},"feeType":{"type":"string","nullable":true,"description":"Type of fee (e.g., 'ATM fee', 'Wire transfer fee')"},"netAmount":{"type":"number","nullable":true,"description":"Net amount after fees"},"source":{"type":"string","nullable":true,"description":"Source of the transaction"},"type":{"type":"string","nullable":true,"description":"Transaction type"},"provider":{"type":"string","enum":["Plaid","GoCardless","Stripe","Mercury"],"description":"The data provider for this transaction"},"accountId":{"type":"string","description":"ID of the account this transaction belongs to"}}},"TransactionCategory":{"type":"object","required":["id","name","group","description"],"properties":{"id":{"type":"string","description":"Unique identifier for the category (v2 category ID)"},"name":{"type":"string","description":"Category name (e.g., 'Taxi', 'Groceries')"},"group":{"type":"string","nullable":true,"description":"Category group (e.g., 'TRANSPORTATION', 'FOOD_AND_DRINK')"},"description":{"type":"string","nullable":true,"description":"Description of what the category covers"}}},"TransactionsListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["transactions","categories"],"properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"},"description":"List of transactions"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/TransactionCategory"},"description":"List of categories referenced by the transactions in this response"}}},"meta":{"type":"object","required":["count","nextPage"],"properties":{"count":{"type":"integer","description":"Number of transactions in this response"},"nextPage":{"type":"string","nullable":true,"description":"URL to fetch the next page of results. Null if no more results are available."}}}}},"Holding":{"type":"object","required":["id","accountId","securityId","quantity","costBasis","institutionPrice","institutionValue","currency","priceAsOf","provider"],"properties":{"id":{"type":"string","description":"Unique identifier for the holding (format: accountId:securityId)"},"accountId":{"type":"string","description":"ID of the account this holding belongs to"},"securityId":{"type":"string","description":"ID of the security. Use this to look up security details in the securities array."},"quantity":{"type":"number","nullable":true,"description":"Number of shares/units held"},"costBasis":{"type":"number","nullable":true,"description":"Total cost basis (original purchase value)"},"institutionPrice":{"type":"number","nullable":true,"description":"Current price per share as reported by the institution"},"institutionValue":{"type":"number","nullable":true,"description":"Current total value (quantity * institutionPrice). Null if quantity or price is unavailable."},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency code (e.g., 'USD')"},"priceAsOf":{"type":"string","nullable":true,"description":"Date of the price quote (ISO 8601 format)"},"provider":{"type":"string","enum":["Plaid"],"description":"The data provider for this holding (currently only Plaid)"}}},"Security":{"type":"object","required":["id","symbol","name","type"],"properties":{"id":{"type":"string","description":"Unique identifier for the security"},"symbol":{"type":"string","nullable":true,"description":"Ticker symbol (e.g., 'AAPL', 'VTI')"},"name":{"type":"string","nullable":true,"description":"Full name of the security"},"type":{"type":"string","nullable":true,"description":"Security type (e.g., 'equity', 'etf', 'mutual fund', 'fixed income')"}}},"HoldingsListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["holdings","securities"],"properties":{"holdings":{"type":"array","items":{"$ref":"#/components/schemas/Holding"},"description":"List of holdings"},"securities":{"type":"array","items":{"$ref":"#/components/schemas/Security"},"description":"List of securities referenced by the holdings in this response"}}},"meta":{"type":"object","required":["count","totalCount","hasMore","nextPage"],"properties":{"count":{"type":"integer","description":"Number of holdings in this response"},"totalCount":{"type":"integer","description":"Total number of holdings available"},"hasMore":{"type":"boolean","description":"Whether more results are available"},"nextPage":{"type":"string","nullable":true,"description":"URL to fetch the next page of results. Null if no more results are available."}}}}},"InvestmentTransaction":{"type":"object","required":["id","accountId","securityId","type","subtype","date","quantity","price","amount","fees","currency","description","provider"],"properties":{"id":{"type":"string","description":"Unique identifier for the investment transaction"},"accountId":{"type":"string","description":"ID of the account this transaction belongs to"},"securityId":{"type":"string","nullable":true,"description":"ID of the security. Use this to look up security details in the securities array. Null for cash transactions."},"type":{"type":"string","nullable":true,"enum":["buy","sell","cancel","cash","fee","transfer","other"],"description":"Transaction type (buy, sell, cancel, cash, fee, transfer, other)"},"subtype":{"type":"string","nullable":true,"description":"Transaction subtype (e.g., 'trade', 'dividend', 'contribution', 'withdrawal')"},"date":{"type":"string","format":"date","description":"Date of the transaction (ISO 8601 format)"},"quantity":{"type":"number","description":"Number of shares/units involved in the transaction. Negative for sells."},"price":{"type":"number","description":"Price per share/unit at time of transaction"},"amount":{"type":"number","description":"Total transaction amount. Negative for outflows (buys), positive for inflows (sells, dividends)."},"fees":{"type":"number","description":"Fees associated with the transaction"},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency code (e.g., 'USD')"},"description":{"type":"string","description":"Human-readable description of the transaction"},"provider":{"type":"string","enum":["Plaid"],"description":"The data provider for this transaction (currently only Plaid)"}}},"InvestmentTransactionsListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["investmentTransactions","securities"],"properties":{"investmentTransactions":{"type":"array","items":{"$ref":"#/components/schemas/InvestmentTransaction"},"description":"List of investment transactions"},"securities":{"type":"array","items":{"$ref":"#/components/schemas/Security"},"description":"List of securities referenced by the transactions in this response"}}},"meta":{"type":"object","required":["count","totalCount","hasMore","nextPage"],"properties":{"count":{"type":"integer","description":"Number of transactions in this response"},"totalCount":{"type":"integer","description":"Total number of transactions available"},"hasMore":{"type":"boolean","description":"Whether more results are available"},"nextPage":{"type":"string","nullable":true,"description":"URL to fetch the next page of results. Null if no more results are available."}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}}},"security":[{"bearerAuth":[]}]}