Accounts

Every account carries two separate fields. collection is yours: whether we retrieve it. status and status_detail are ours: what the portal showed on the last completed run. "You turned this off" and "this broke" are never the same field.

GET /v1/connections/{connection_id}/accounts returns the connection with an accounts array. Each account has account_id, connection_id, account_number, account_number_as_printed, service_address, collection, status, status_detail, customer_action_required (false today: an account never waits on you by itself), first_seen and last_statement_date, and an active account adds next_expected_statement_date.

{
  "account_id": "acc_bf1318e1-8ea7-48ac-9828-647371c76c79",
  "connection_id": "con_8d62c46f-d186-427c-9610-2711def78c57",
  "account_number": "1000000101",
  "account_number_as_printed": "1000-0001-01",
  "service_address": "100 Example Street, Springfield",
  "collection": "active",
  "status": "connection_success",
  "status_detail": "data_accessible",
  "customer_action_required": false,
  "first_seen": "2026-10-13",
  "last_statement_date": "2026-09-28",
  "next_expected_statement_date": "2026-10-28"
}

Account numbers. account_number is the matching form: letters and digits only, upper case, the same as a statement's normalized, so 1000-0001-01 and 1000000101 are one account. account_number_as_printed is the portal's own text. Some portals list an account under a different form than its bills print (a location code, a composite, an extra prefix). The statement then carries the bill's own number, and account_id links the two. Use account_id, not the number, to tie a statement to the account you activated. The child accounts of a summary bill follow their summary: activating the summary delivers its children's statements too.

Expected accounts. PUT /v1/expected-accounts takes {"provider": "...", "account_numbers": ["..."]} and answers with provider and expected_count, the number of numbers newly added. It replaces the numbers not yet found for that provider, across all your connections to it; a number already matched to an account stays matched and is not counted again. A number that is already a known never_collected account activates at once, and any other activates when a run finds it. A paused account is never reactivated by this list.

Missing accounts are the report most worth acting on. An account the portal stops listing usually means it was closed, moved to another login, or the portal changed. It turns connection_error / not_listed_by_portal on the run that first notices, appears in that event's missing_accounts, and returns to connection_success by itself if it reappears. Its collection never changes on its own.

Portals read selectively. On some portals a regular run reads only the accounts you collect, which keeps large logins fast. There, an account you do not collect is neither reported missing nor discovered by a regular run. A discovery run lists them all: the first run of every connection is one, and you can ask for another at any time with {"mode": "discover"}.

Shortfalls. Portals sometimes list only part of a login's accounts. A run that sees fewer than 80% of the accounts listed before, once a login has five or more, is treated as a partial run: nothing is marked missing, the event's enumeration block shows the counts, and the run is retried.