Skip to main content
Users in Breadbox represent family members within a household — they are organizational labels, not login accounts. Each user can own one or more bank connections and accounts, and transactions can be filtered or attributed to a specific user. The users endpoint returns all family members in a single unpaginated response, since a household typically has very few members.

​
List users

GET /api/v1/users
Returns all family members configured in Breadbox. The response is not paginated. Auth: Read

​
Query parameters

None.

​
Response

{
  "data": [
    {
      "id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
      "short_id": "Kp2qRs3t",
      "name": "Alex Canales",
      "email": "alex@example.com",
      "created_at": "2025-11-01T09:00:00Z",
      "updated_at": "2025-11-01T09:00:00Z"
    },
    {
      "id": "u2b3c4d5-e6f7-890a-bcde-f12345678901",
      "short_id": "Lq3rSt4u",
      "name": "Jordan Canales",
      "email": null,
      "created_at": "2025-11-15T12:00:00Z",
      "updated_at": "2025-11-15T12:00:00Z"
    }
  ]
}

curl -H "X-API-Key: bb_your_key" \
  "http://localhost:8080/api/v1/users"

​
Response fields

​
id
string (UUID)
required
Breadbox-assigned UUID for this user. Pass this as user_id in transaction and account filters.
​
short_id
string
required
8-character base62 alias. Accepted interchangeably with id where user_id is a path or query parameter.
​
name
string
required
Display name of the family member (e.g., "Alex Canales").
​
email
string
Optional email address. Used for display purposes only — not for authentication or notifications. null if not set.
​
created_at
string (ISO 8601)
required
Timestamp when this user record was created.
​
updated_at
string (ISO 8601)
required
Timestamp when this user record was last updated.

​
How users relate to other resources

Users are the top-level ownership entity in Breadbox. The relationship flows downward: 
User → Connections → Accounts → Transactions
  • Each connection is assigned to a user, identifying which family member linked that bank.
  • Each account inherits ownership from its connection’s user.
  • Each transaction is filtered by user via COALESCE(attributed_user_id, account.user_id). This attribution-aware logic means transactions can be reassigned to a different household member from the account default.
Use the user_id query parameter on GET /api/v1/accounts and GET /api/v1/transactions to filter data to a specific family member.

​
Error codes

ConditionStatusCode
Missing X-API-Key header401MISSING_API_KEY
Invalid or revoked key401INVALID_API_KEY / REVOKED_API_KEY