Status API

The Status API tracks a user's open-banking journey from first consent through to insights being generated. It is a read-only window; it does not trigger processing, it only reflects what has already happened.

Consistency

The API is eventually consistent: there may be a short delay between an action occurring and the status reflecting it.

Core concepts & Definitions

User - Each end-user (person) has their journey tracked by this API, identified by the tenantUserId / userId in their auth token. The status reflects everything that has ever happened for that user in Ockto Open Banking across all its entities.

Session entities - Created each time a new authentication token is requested for the user. A user can accumulate multiple sessions over time as they start new open-banking flows. Sessions are informational — they always have status STARTED and serve as a timestamp marker for when a new authentication flow began.

Consent entities - Permission a user grants to access their provider data. When a user links the provider bank accounts for a given provider, that creates one consent. If they also link another provider, that is a second consent. Each consent goes through its own lifecycle. Roughly: created → validated at the provider → accounts retrieved → transactions & balances retrieved.

Account entities - A specific provider account under a consent, for example a current account or a savings account. One consent can give access to multiple accounts. Each account has its own independent status — accounts under the same consent may be at different stages simultaneously.

Transaction set entities - Represents a batch of transactions retrieved for one account. One account can have one or more transaction sets, each with its own lifecycle from retrieval through to processing.

The hierarchy is: user → sessions → consents → accounts → transaction sets.

When to use each endpoint

Authentication and identification

Every endpoint requires authentication. Use the same JWT token as for the other Ockto Open Banking API calls, via the header Authorization: Bearer YOUR_SECRET_TOKEN.

For the /user* endpoints the JWT is directly linked to the userId; every response is automatically scoped to that user. The /providers* endpoints return a global, non-user aggregate of bank availability, so they ignore the token's user claim — any valid token may read them, and they can be consulted before a user session exists.

Status values

Each level of the hierarchy (user, session, consent, account, transaction set) has its own status field that reflects how far that entity has progressed.

Note: All below statuses are plain strings - not strict enums. Statuses may be added in future without prior notice. Always handle unknown values gracefully.

Overall user status

The top-level status on all three endpoints. Reflects the minimum across all active entities; it is only as far as the least-progressed entity. So if e.g. 3 accounts are in INSIGHTS_GENERATED but 1 is in TRANSACTION_SET_RETRIEVED, the user status can never be higher than TRANSACTION_SET_RETRIEVED. And if a new consent is just created, the user status will never be higher than CONSENT_CREATED because the new consent has not yet progressed. The current user flow:

STARTED → CONSENT_CREATED → CONSENT_VALID → ACCOUNTS_RETRIEVING → TRANSACTIONS_RETRIEVING → TRANSACTIONS_RETRIEVED → TRANSACTIONS_CATEGORISED → INSIGHTS_GENERATED

Also possible: CONSENT_CANCELLED, DELETED (terminal)

Entity: consent status

CONSENT_CREATED → CONSENT_VALID → CONSENT_RETRIEVED

Terminal values: CONSENT_TERMINATED, CONSENT_CANCELLED, CONSENT_DELETED

Entity account status

Account status reflects the progress of its transaction sets — it is the least-progressed transaction set under that account.

ACCOUNT_RETRIEVED → TRANSACTION_SET_RETRIEVING → TRANSACTION_SET_RETRIEVED → PROCESSING_COMPLETED → INSIGHTS_GENERATED

Also possible: TRANSACTION_SET_DELETED

Entity transaction set status

TRANSACTION_SET_RETRIEVING → TRANSACTION_SET_RETRIEVED → PROCESSING_COMPLETED → INSIGHTS_GENERATED

Also possible: TRANSACTION_SET_DELETED

Known behaviors

Status can drop when a user adds a new consent. When a user links another provider (bank account), the user-level status drops back to CONSENT_CREATED for the new consent and advances again as processing completes. This is expected: the status is only as far as the least-progressed active entity.

Status values may be skipped. Not all intermediate statuses are guaranteed to appear. The API always reflects the most current known state — when a step is skipped, the status advances directly to the furthest progressed value.

Deletion. Once a user's data has been deleted, the status endpoint returns the last known state at the time of deletion.

One-time journeys only. This API tracks one-time open-banking journeys: the user grants consent, data is retrieved and processed once, and the journey ends. It does not support continuous open consents where transactions are kept in sync over time.

Timestamps. All timestamps reflect when the event was recorded by the API, not necessarily the exact moment the real-world action occurred.