Useful integration patterns

Choose an operation according to the question your integration answers. Paths below are relative to /api/v1; use the catalog for exact methods and scopes.

Account reader

Fetch GET /v2/accounts with read:finance. Preserve each account’s currency and balance basis. Do not sum unlike currencies without supported conversion evidence. If the answer is unavailable, surface that state.

Recent activity reader

Fetch GET /v2/transactions with a bounded page_size. Deduplicate by stable record ID and inspect pagination metadata. Label the result recent or paginated activity, not complete financial history.

See pagination before implementing multi-page traversal.

Upcoming commitments

Read GET /v2/obligation-board with read:finance. Retain due dates, status, amounts and currency. A fictional EGP 350 bill due 10 October 2026 is expected work, not proof EGP 350 left an account.

Import progress monitor

Use imports:read to inspect GET /v2/imports/:job and the relevant rows. A monitor can explain progress without starting the job. Starting, undoing or reprocessing needs explicit imports:write intent and the correct reviewed version.

Before adding writes

Read financial safety and idempotency. Provide a user-visible action and recovery outcome. Do not let a background summary reader silently become a money-recording agent.