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.

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.
• 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 supersede the previous ones on every report endpoint (/report, /reports, /reports.zip, PDF and XML). Earlier versions are retained as history but no longer served.
• The request stays ready — the customer’s ongoing consent is their authorisation for ongoing disclosure, so there is no second share step. A report.refreshed webhook fires and any configured report email is re-sent.
• 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: 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.

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.