Requests & consent

A request represents one customer sharing their bank data to produce one report. It moves through a short lifecycle from creation, to consent, to a finished report.

Create a request

curl -X POST https://api.statementiq.com.au/v1/requests \
  -H "X-API-Key: siq_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Jordan Wilson",
    "report_type": "expense_summary",
    "client_ref": "MATTER-1024",
    "email": "jordan@example.com",
    "phone": "+61400000000"
  }'

Fields:

• client_name (required) — the customer’s name, shown on the report.
• report_type (required) — expense_summary or affordability. See Reports & formats.
• client_ref — your own reference, echoed back to you.
• email, phone — optional; pre-fill the invite fields and (in production) let us deliver the consent link.
• redirect_uri, cancel_uri — optional URLs to return the customer to after they finish or cancel.
• collect_multiple — optional; ask the customer to connect every bank they use (see below). Omitted, it takes your company’s default from Portal → Settings → Multiple banks.
• collect_reason — optional; the reason shown to the customer between banks. Omitted, it takes your company’s configured reason.
• report_breakdowns — optional; which documents to produce, any of summary, by_bank, by_bank_account. Omitted, it takes your company’s default from Portal → Settings. One analysis and one charge however many you pick — see Reports & formats.
• return_url — optional; where the customer is sent once they’ve shared their report. Must be https; we append request_id so you can resume your own flow. Omitted, it takes your company’s default from Portal → Settings → After sharing, which is set separately for sandbox and production — so test journeys land on your staging site, not your live one. Not to be confused with redirect_uri, which is where they land after the bank step.
• consent_mode — optional; once_off (default) revokes the customer’s bank consent once the report is generated, so the connection is single-use; ongoing keeps it live for its full duration so you can pull refreshed data later. Omitted, it takes your company’s default from Portal → Settings → Consent retention. In production, ongoing needs approval first (see Refreshing an ongoing connection); the response’s consent_mode shows which applied.
• budget_template — afsa_part_ix adds a fortnightly household budget on the AFSA Part IX debt-agreement lines to the expense summary; none switches it off for this request. Omitted uses your Settings default (Portal → Settings → Budget template).

Response:

{
  "id": "req_1a2b3c…",
  "status": "pending_consent",
  "report_type": "expense_summary",
  "consent_url": "https://statementiq.com.au/connect/req_1a2b3c…",
  "collect_multiple": false
}

Asking for all of a customer’s banks

Some assessments need the customer’s complete financial picture. Create the request with collect_multiple: true (or switch the default on in Portal → Settings) and the consent journey changes shape:

• After each bank connects, the customer is invited to connect their next bank — with your collect_reason shown as the why, and a running list of the banks they’ve already connected.
• The report is only generated once they confirm they’ve added every bank(“That’s all my banks” on their secure page). Until then the request stays pending_consent— you’ll never receive a partial, single-bank report from a multi-bank request.
• The finished report covers every connected bank: per-account sections in affordability, a combined position in expense_summary.

A reason that works well: “To assess your situation fairly we need a complete picture of your finances — please connect every bank you use, including the account your pay goes into.”

Share the consent link

Hand consent_url to your customer. It opens a page that explains what’s happening, then hands off to the secure CDR consent flow — the customer picks their bank and authorises sharing with a one-time code. No login is required for them, and no banking password is ever shared with us.

Sending it by email or SMS

curl -X POST https://api.statementiq.com.au/v1/requests/req_1a2b3c/invite \
  -H "X-API-Key: siq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "to": "jordan@example.com" }'

Your customer reviews and shares the report

Once the bank data arrives, StatementIQ prepares the report and shows it to your customer first, on their secure link. They review it and share it with you in one tap. This is a Consumer Data Right requirement — under the CDR the report is derived from their data and is theirs to share — and it doubles as a natural accuracy check. You’ll see the request at pending_share during this step, and fetching the report returns 409 until they share. The moment they do, the request becomes ready, the report.ready webhook fires, and the report is available in the portal and API.

Request status

Poll a request to follow its progress. status is one of:

• pending_consent — portal gate 1, Awaiting bank connection.
• pending_data — portal gate 2, Preparing report; bank access has been granted. The report is built once every account the customer consented to sharehas delivered its transactions — banks send accounts one at a time, usually within a minute. If an account still hasn’t arrived a few minutes after consent, the report is built anyway and that account is listed in its data_gaps (see Reports), never silently shown as an empty account.
• pending_share — portal gate 3, Awaiting customer share; the report is prepared and the customer is reviewing it.
• ready — portal gate 4, Shared with you; the report is available to your company.
• withdrawn — consent was withdrawn; derived data has been deleted.
• purged — past the retention window; the report has been deleted, the audit record kept.

List all your requests with GET /v1/requests (scoped to the environment of the key you use). Prefer webhooks over polling for production.

Refreshing an ongoing connection

A request created with consent_mode: ongoingkeeps the customer’s bank connection live for the sharing period they chose at their bank (up to 12 months). Once they’ve shared the report, you can re-pull the live feed and re-run the analysis without sending them through consent again:

curl -X POST https://api.statementiq.com.au/v1/requests/req_1a2b3c…/refresh   -H "X-API-Key: siq_test_your_key"

{ "id": "req_1a2b3c…", "status": "ready", "verification_id": "SIQ-9C21D4A0" }

• The refreshed documents get a new verification id and become what every report endpoint returns (/report, /reports, /reports.zip, PDF, CSV and XML). Earlier versions are kept, never overwritten: list them with GET /v1/requests/{id}/versions and read any one by passing its verification id as ?version= to the same endpoints (see below).
• In the portal, a shared ongoing request has a Refresh report button, and its earlier versions are listed under Versions for download.
• The request stays ready. Before they connect and again when they share, the customer is told that sharing gives you updated reports until their consent ends, so there is no second share step. A report.refreshed webhook fires and any configured report email is re-sent.
• Production needs approval. Ask for ongoing consent under Updated reports in your production application (Portal → Go live). Until it’s approved, an explicit consent_mode: ongoing on a live request returns 403, and a Settings default of ongoing creates live requests as once_off. Sandbox needs no approval.
• A refresh is not billed as a new assessment.
• How often: one refresh per request per hour. How fresh the data is depends on when the bank was last synced, so refreshing more than a few times a day gains nothing. Weekly or monthly is the natural cadence for a standing arrangement.
• Errors: 403 if ongoing consent isn’t approved for your company in production; 409 if the request isn’t ready yet, if its consent is once_off, or if no data comes back because the customer has withdrawn or their consent has expired at the bank (the previous report is left untouched); 429 with Retry-After inside the cooldown.
• GET /v1/requests/{id} returns consent_mode, refreshed_at and refreshable — whether a refresh would be accepted now, cooldown aside — so you can offer it only where it works.

Report versions

Every analysis the request has produced, newest first: the first report, then one per refresh. current marks the one the report endpoints return by default.

{ "versions": [
  { "verification_id": "SIQ-9C21D4A0", "generated_at": "2026-11-24T02:10:04.120000+00:00", "views": 1, "current": true },
  { "verification_id": "SIQ-684CECF6", "generated_at": "2026-10-24T02:28:40.053781+00:00", "views": 1, "current": false }
] }

curl "https://api.statementiq.com.au/v1/requests/req_1a2b3c…/report.pdf?version=SIQ-684CECF6" \
  -H "X-API-Key: siq_test_your_key" -o earlier.pdf

?version= works on /report, /report.html, /report.pdf, /report.xml, /report.csv, /reports and /reports.zip, alongside breakdown and scope; an unknown version is 404. Like the report itself, versions are available once the customer has shared, and all of them are deleted together on withdrawal or at the retention limit.

Withdrawal & deletion

A customer can withdraw at any time from their own consent page, and you can withdraw on their behalf. Withdrawal deletes the derived report and removes the upstream CDR consent. Derived reports are also deleted automatically after the retention window (90 days by default). A minimal audit record — that a request existed and what happened to it — is kept for compliance and contains no banking data.