Skip to main content
The accounts endpoints return the bank accounts Breadbox has synced from your connected institutions. Each account includes current balance information, account type, and the last four digits of the account number. Accounts are not paginated — a household typically has fewer than twenty accounts, so all results fit in a single response.

​
List all accounts

GET /api/v1/accounts
Returns all bank accounts known to Breadbox, ordered alphabetically by institution name and then by account name. Soft-deleted accounts and accounts belonging to disconnected connections are excluded. Auth: Read

​
Query parameters

​
user_id
string (UUID)
Filter to accounts assigned to a specific family member. Accepts the user’s full UUID or short ID. If omitted, all accounts across all users are returned. An unknown user_id returns an empty data array rather than a 404.

​
Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "short_id": "Xk3mPqR7",
      "connection_id": "c9d8e7f6-a5b4-3210-fedc-ba0987654321",
      "user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
      "user_name": "Alex Canales",
      "name": "Platinum Checking",
      "official_name": "Chase Total Checking®",
      "type": "depository",
      "subtype": "checking",
      "mask": "4821",
      "iso_currency_code": "USD",
      "balance_current": 3241.87,
      "balance_available": 3191.87,
      "balance_limit": null,
      "institution_name": "Chase",
      "created_at": "2025-11-01T09:00:00Z",
      "updated_at": "2026-02-28T14:30:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "short_id": "Yt4nQsS8",
      "connection_id": "c9d8e7f6-a5b4-3210-fedc-ba0987654321",
      "user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
      "user_name": "Alex Canales",
      "name": "Sapphire Reserve",
      "official_name": "Chase Sapphire Reserve®",
      "type": "credit",
      "subtype": "credit card",
      "mask": "7743",
      "iso_currency_code": "USD",
      "balance_current": 1842.50,
      "balance_available": 18157.50,
      "balance_limit": 20000.00,
      "institution_name": "Chase",
      "created_at": "2025-11-01T09:00:00Z",
      "updated_at": "2026-02-28T14:30:00Z"
    }
  ]
}

​
Example

curl -H "X-API-Key: bb_your_key" \
  "http://localhost:8080/api/v1/accounts?user_id=u1a2b3c4-d5e6-f789-0abc-def123456789"

​
Get a single account

GET /api/v1/accounts/{id}
Returns a single bank account by its Breadbox UUID or short ID, including full balance details. Auth: Read

​
Path parameters

​
id
string
required
The account’s Breadbox UUID (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890) or 8-character short ID (e.g., Xk3mPqR7).

​
Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "short_id": "Xk3mPqR7",
  "connection_id": "c9d8e7f6-a5b4-3210-fedc-ba0987654321",
  "user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "user_name": "Alex Canales",
  "name": "Platinum Checking",
  "official_name": "Chase Total Checking®",
  "type": "depository",
  "subtype": "checking",
  "mask": "4821",
  "iso_currency_code": "USD",
  "balance_current": 3241.87,
  "balance_available": 3191.87,
  "balance_limit": null,
  "institution_name": "Chase",
  "created_at": "2025-11-01T09:00:00Z",
  "updated_at": "2026-02-28T14:30:00Z"
}

​
Example

curl -H "X-API-Key: bb_your_key" \
  "http://localhost:8080/api/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
Response fields

​
id
string (UUID)
required
Breadbox-assigned UUID. Use this to reference the account in other API calls.
​
short_id
string
required
8-character base62 alias. Accepted interchangeably with id in path parameters.
​
connection_id
string (UUID)
UUID of the parent bank connection. May be null if the connection was removed — the account is preserved for historical queries.
​
user_id
string (UUID)
UUID of the family member this account is assigned to. null if the account has not been assigned to a user.
​
user_name
string
Display name of the owning family member. Resolved from the users table.
​
name
string
required
Short account name as provided by the institution (e.g., "Platinum Checking").
​
official_name
string
Full official product name from the institution (e.g., "Chase Total Checking®"). May be null.
​
type
string
required
Plaid account type. One of: depository, credit, loan, investment, other.
​
subtype
string
Plaid account subtype. Examples: checking, savings, credit card, mortgage. May be null.
​
mask
string
Last 2–4 digits of the account number for display purposes (e.g., "4821"). May be null.
​
balance_current
number
Current balance. For depository accounts: total funds in the account. For credit accounts: the amount currently owed — a positive balance_current on a credit account means money is owed to the institution. May be null if the provider did not return a balance.
​
balance_available
number
Available balance. For depository accounts: funds available after pending transactions. For credit accounts: remaining available credit. Frequently null for credit accounts. May be null if not reported by the provider.
​
balance_limit
number
Credit limit for credit accounts, or overdraft limit for some depository accounts. null for accounts without a limit.
​
iso_currency_code
string
ISO 4217 currency code for the balance values (e.g., "USD"). null if the account uses a non-standard currency code.
​
institution_name
string
required
Human-readable name of the financial institution (e.g., "Chase").
​
created_at
string (ISO 8601)
required
Timestamp when this account record was first created in Breadbox.
​
updated_at
string (ISO 8601)
required
Timestamp when this account record was last updated (for example, after a balance refresh).

​
Error codes

ConditionStatusCode
Missing X-API-Key header401MISSING_API_KEY
Invalid or revoked key401INVALID_API_KEY / REVOKED_API_KEY
user_id is not a valid UUID400INVALID_PARAMETER
Account not found404NOT_FOUND