Reporting & Data Export
Three separate records exist for a tenant, and it is worth keeping them apart:
- Usage records — one row per API request, used for the monthly quota and for reporting.
- The raw export — a paged dump of your own operational tables, JSON or CSV.
- The audit trail — an append-only record of security-relevant actions.
1. Usage
GET /api/v1/admin/usage — roles superuser or admin.
Every API request routed to your tenant hostname writes one usage record: the tenant, the acting
system user or subject, the endpoint, the HTTP method, whether the request invoked an AI service
(is_ai), the request size in bytes (bandwidth_bytes) and the timestamp. Files the web server
serves directly — the admin console, the hosted verification UI and their assets — and the health
and metrics endpoints are not routed through the API and are not counted.
The request count is what the plan quota applies to: past requests_per_month the API
answers 429. The other recorded fields — request size, AI flag — are reported for your own
analysis; they are not metered and no limit is applied to them.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | yes | aggregated for totals, raw for the individual rows. |
date | string | no | A range, YYYY-MM-DD,YYYY-MM-DD. Maximum span 32 days; a longer or malformed range is 400. |
limit | int | no | type=raw only. Default 100, maximum 1000. |
offset | int | no | type=raw only. Default 0. |
Aggregated
curl "https://acme.identiwise.com/api/v1/admin/usage?type=aggregated&date=2026-08-01,2026-08-31" \
-H "Authorization: Bearer YOUR_SYSTEM_TOKEN"
{
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"total_requests": 1500,
"ai_requests": 420,
"bandwidth_bytes": 52428800,
"days_in_range": 31,
"plan_limits": { "requests_per_month": 5000 },
"plan_usage": { "requests_used_this_month": 1500 }
}
plan_limits and plan_usage describe the enforced monthly quota, so you can warn your own
operators before the 429 arrives.
Raw
curl "https://acme.identiwise.com/api/v1/admin/usage?type=raw&limit=5" \
-H "Authorization: Bearer YOUR_SYSTEM_TOKEN"
The response is {"type":"raw","data":[…]} plus the same plan_limits / plan_usage. Each row
carries id, tenant_id, system_user_id, subject_id, endpoint, method, is_ai,
bandwidth_bytes and created_at, newest first. id and subject_id are UUID strings;
subject_id is null for requests made with a system credential.
2. Raw data export
GET /api/v1/admin/raw — superuser only, and available on plans that include the export;
where it is not included the endpoint answers 403.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
table | string | yes | One of the tables below. |
format | string | no | json (default) or csv. |
since | string | no | YYYY-MM-DD; rows created on or after that date. An invalid date is 400. |
limit | int | no | Default 100, maximum 1000. |
offset | int | no | Default 0. |
Exportable tables
| Table | Contents |
|---|---|
subjects | The identity records you created. |
ident_user_license | Document submissions: attempt, review state, OCR score, AI detail. |
ident_user_selfies | Selfie submissions and their review state. |
submissions | Licences and selfies combined into one timeline. |
verification_correspondence | Messages exchanged between administrators and subjects. |
photo_uploads_history | Every stored object key ever recorded for the tenant. |
subject_deletion_requests | Erasure requests and their disposition. |
usage_records | The per-request rows described above. |
system_users | Your staff accounts (never password material). |
api_tokens | Token metadata (never the secret). |
curl "https://acme.identiwise.com/api/v1/admin/raw?table=subjects&format=csv&limit=1000" \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN" \
--output subjects.csv
Everything returned is scoped to your tenant; the predicate is applied in every query and checked in CI.
Every run writes an audit row before any data leaves. If that record cannot be written the
export returns 503 with a Retry-After header and no rows at all — an export must not be
possible without a trace of it.
3. Audit trail
Security-relevant actions are written to an append-only audit table: who acted, on which tenant, what they did, to what, whether it succeeded, the source address, a bounded detail object, and the time. Values are never recorded — a record of a change to a subject names the fields written, never their contents — and no credential, second factor, pre-signed URL or image ever appears in a row.
Recorded actions today:
| Area | Actions |
|---|---|
| Data access | document.viewed (a pre-signed photo URL issued or refused), records.listed (a bulk read of subjects, submissions, the review queue, staff or tokens), raw_export.run |
| Verification | review.decided (approve, reject or use-as-reference) |
| Subject records | subject.changed (created or rewritten, by staff or by the subject), subject.deletion_requested, subject.deleted, submission.deleted |
| Authentication | auth.login (refused, challenged or granted, on either service), auth.2fa (a second-factor verification outcome), auth.2fa_changed (enrolled, disabled, reset, recovery codes regenerated), password.changed |
| Authorisation | authz.denied (an authenticated principal refused by a role or ownership gate), role.changed, staff.changed, staff.inspected |
| Credentials | api_token.created, api_token.revoked, ephemeral_token.issued, ephemeral_token.refused, token_config.changed (a preset or workflow created, changed or deleted) |
Records that grant access to identity data — a pre-signed photo URL, the raw export — are written before the access and fail closed. Outcome records written after the fact (a review decision, an erasure) are best-effort, because refusing the response could not undo an action that already committed.
The trail is written but is not exposed through an API endpoint today; it is not one of the tables the raw export offers. If you need an extract for an investigation or a supervisory authority, write to privacy@identiwise.com. A retention and export path for the trail is on the roadmap.
4. What reporting does not do
- There are no webhooks or callbacks. A verification result comes back in the HTTP response
to the upload. To learn about later changes — an administrator's decision, a new submission —
poll
GET /api/v1/admin/revieworGET /api/v1/admin/submissionsfrom your backend. - There is no automated purge. Data is kept until it is erased on request or by you. An automated retention clock is on the roadmap and is not live.