Overview
| Base URL | https://portal.australianidentitysolutions.com.au |
| Version | v1 (paths start /api/v1) |
| Format | JSON request and response bodies, snake_case field names, HTTPS only |
| Spec | https://portal.australianidentitysolutions.com.au/api/v1/openapi.json |
The live spec is public. Import it into Postman, Insomnia or a code generator:
curl https://portal.australianidentitysolutions.com.au/api/v1/openapi.json -o ais-openapi-v1.jsonAuthentication
Server endpoints take your secret key as a Bearer token:
Authorization: Bearer ais_live_YOUR_SECRET_KEY
# or, in test mode:
Authorization: Bearer ais_test_YOUR_TEST_SECRET_KEY- The older
x-api-key: ais_live_...header is still accepted. - The key decides the mode: test keys only see test checks, live keys only see live checks.
- Secret keys are for servers only. Browser endpoints (the SDK group below) take a publishable key (
ais_pk_live_/ais_pk_test_) or a client token (ais_ct_, valid 1 hour, one check only), and never return results.
Conventions
| Topic | How it works |
|---|---|
| Request-Id | Every response has a Request-Id header (req_...). Quote it if you contact us. |
| Timestamps | Unix seconds (created_at, started_at, completed_at, expires_at). |
| Idempotency | Send Idempotency-Key (1 to 255 printable characters, a UUID is ideal) on POST requests. The same key and body within 24 hours returns the first response with Idempotent-Replayed: true. 5xx responses are not stored, so you can retry them. |
| Pagination | Lists are newest first. Pass the last id you received as starting_after while has_more is true. limit is 1 to 100 (default 20). |
| Rate limits | 100 requests per minute per account and mode for server endpoints; 30 per minute for browser (SDK) endpoints. A 429 carries Retry-After in seconds. |
| Body size | Request bodies up to 16 KB. |
| Metadata | Up to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total. |
| Charging | A live check is charged once, when it completes (approved or declined). A check in review is charged once, when it ends approved or declined. Abandoned, expired and cancelled checks are not charged. Test checks are never charged. |
Errors
Errors use the matching HTTP status and this body. param is present when one field is at fault.
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "customer.email: must be a valid email address",
"param": "customer.email"
}
}Error types
| type | HTTP status | Meaning |
|---|---|---|
invalid_request_error | 400, 404, 409, 413 | Something about the request is wrong (bad parameter, unknown id, wrong state). |
authentication_error | 401 | Missing, invalid or revoked key, or the wrong kind of key for the endpoint. |
permission_error | 403 | The browser origin is not in your Allowed domains. |
billing_error | 402 | Live mode: your credit does not cover the check. |
idempotency_error | 400, 409 | A problem with the Idempotency-Key header. |
rate_limit_error | 429 | Too many requests. Wait for Retry-After seconds. |
api_error | 500 | Something went wrong on our side. Safe to retry. |
Error codes
| code | Status | Meaning |
|---|---|---|
parameter_invalid | 400 | A field failed validation. param names it, for example customer.email. |
invalid_json | 400 | The body is not valid JSON. |
body_too_large | 413 | The body is over 16 KB. |
missing_api_key | 401 | No Authorization (or x-api-key) header. |
invalid_api_key | 401 | The key is invalid or has been revoked. |
secret_key_required | 401 | This endpoint needs a secret key (ais_live_ or ais_test_). |
wrong_key_type | 401 | This endpoint needs a publishable key (ais_pk_live_ or ais_pk_test_). |
invalid_client_token | 401 | The client token is invalid or has expired. Create a new one. |
insufficient_credit | 402 | Live mode: top up, or wait for included checks to renew. |
origin_not_allowed | 403 | Add the website to Allowed domains in the dashboard. |
resource_missing | 404 | No verification with that id in this account and mode. |
verification_not_cancelable | 409 | Only pending or in_progress checks can be cancelled (not in_review or finished). |
verification_not_open | 409 | Client tokens can only be created for open checks. |
report_not_ready | 409 | The PDF is available once the check is completed (approved or declined). |
idempotency_key_invalid | 400 | Idempotency-Key must be 1 to 255 printable ASCII characters. |
idempotency_key_reused | 400 | That key was already used with a different request. Use a new key. |
idempotency_key_in_use | 409 | A request with that key is still running. Retry shortly. |
rate_limited | 429 | Wait for the number of seconds in Retry-After. |
internal_error | 500 | Retry. If it continues, email us with the Request-Id. |
Verifications
Create and read identity checks.
Create a verification
POST/api/v1/verifications
Creates a check and returns its customer link (verification_url) and a short-lived client_token for the front-end SDK. If customer.email is given we email the link (set send_email: false to deliver it yourself). Without an email, nothing is sent. Live mode checks your credit first and returns 402 if it does not cover the check.
Auth: Secret key (ais_live_ / ais_test_)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Any unique string (a UUID is ideal). Retrying with the same key and body within 24 hours returns the first response. Up to 255 characters. |
Request body (JSON, every field optional)
| Field | Type | Description |
|---|---|---|
customer | object | |
customer.email | string (email) | Up to 254 characters. |
customer.name | string | Up to 200 characters. |
customer.phone | string | Up to 32 characters. Example: "+61400000000". |
reference | string | Your own id for this check (order, customer or case number). Up to 200 characters. |
metadata | Metadata | Up to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total. |
send_email | boolean | Default: true when customer.email is given. |
redirect_url | string (uri) | https only. Where we send the customer after they finish (we add verification_id, status and result). |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Created | VerificationWithClientToken |
| 400 | Invalid request | Error |
| 401 | Missing or invalid key | Error |
| 402 | Not enough credit | Error |
| 409 | Not possible in the current state, or idempotency conflict | Error |
| 429 | Rate limited | Error |
| 500 | Server error | Error |
curl https://portal.australianidentitysolutions.com.au/api/v1/verifications \
-H "Authorization: Bearer $AIS_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1234-verify" \
-d '{
"customer": { "email": "jane@example.com", "name": "Jane Citizen" },
"reference": "order_1234",
"metadata": { "plan": "gold" },
"send_email": false
}'{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "pending",
"result": null,
"reference": "order_1234",
"metadata": {
"plan": "gold"
},
"customer": {
"email": "jane@example.com",
"name": "Jane Citizen",
"phone": null
},
"document": null,
"checks": null,
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"redirect_url": null,
"report_url": null,
"source": "api",
"created_at": 1763540000,
"started_at": null,
"completed_at": null,
"expires_at": 1764144800,
"client_token": "ais_ct_eyJ2IjoiY21pNHgwYWJjMDAwMXh5eiJ9.EXAMPLE_SIGNATURE",
"client_token_expires_at": 1763543600
}List verifications
GET/api/v1/verifications
Newest first. Cursor pagination: pass the last id you received as starting_after.
Auth: Secret key (ais_live_ / ais_test_)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | No | 1 to 100. Default 20. |
starting_after | query | string | No | A verification id; returns the items after it. |
status | query | string | No | pending: created, not opened. in_progress: customer started. in_review: manual review, a result follows. completed: finished (see result). expired/abandoned/canceled: ended without a result, not charged. One of: pending, in_progress, in_review, completed, expired, abandoned, canceled. |
result | query | string | No | One of: approved, declined. |
reference | query | string | No | Up to 200 characters. |
created[gte] | query | integer or string (date-time) | No | Unix seconds or ISO 8601. |
created[lte] | query | integer or string (date-time) | No | Unix seconds or ISO 8601. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | VerificationList |
| 400 | Invalid request | Error |
| 401 | Missing or invalid key | Error |
| 429 | Rate limited | Error |
curl -G https://portal.australianidentitysolutions.com.au/api/v1/verifications \
-H "Authorization: Bearer $AIS_SECRET_KEY" \
-d limit=20 \
-d status=completed \
-d result=approved \
--data-urlencode "created[gte]=2026-11-01T00:00:00Z"{
"object": "list",
"url": "/api/v1/verifications",
"has_more": true,
"data": [
{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "completed",
"result": "approved",
"reference": "order_1234",
"metadata": {
"plan": "gold"
},
"customer": {
"email": "jane@example.com",
"name": "Jane Citizen",
"phone": null
},
"document": {
"type": "driving_licence",
"country": "Australia",
"country_code": "AUS"
},
"checks": {
"document": {
"status": "passed"
},
"face_match": {
"status": "passed",
"score": 96.8
},
"liveness": {
"status": "passed"
},
"aml": {
"status": "passed",
"hits": 0
}
},
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"redirect_url": null,
"report_url": "https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/report.pdf",
"source": "api",
"created_at": 1763540000,
"started_at": 1763540060,
"completed_at": 1763540240,
"expires_at": 1764144800
}
]
}Retrieve a verification
GET/api/v1/verifications/{id}
Auth: Secret key (ais_live_ / ais_test_)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | Verification |
| 401 | Missing or invalid key | Error |
| 404 | Not found | Error |
| 429 | Rate limited | Error |
curl https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz \
-H "Authorization: Bearer $AIS_SECRET_KEY"{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "completed",
"result": "approved",
"reference": "order_1234",
"metadata": {
"plan": "gold"
},
"customer": {
"email": "jane@example.com",
"name": "Jane Citizen",
"phone": null
},
"document": {
"type": "driving_licence",
"country": "Australia",
"country_code": "AUS"
},
"checks": {
"document": {
"status": "passed"
},
"face_match": {
"status": "passed",
"score": 96.8
},
"liveness": {
"status": "passed"
},
"aml": {
"status": "passed",
"hits": 0
}
},
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"redirect_url": null,
"report_url": "https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/report.pdf",
"source": "api",
"created_at": 1763540000,
"started_at": 1763540060,
"completed_at": 1763540240,
"expires_at": 1764144800
}Cancel an open verification
POST/api/v1/verifications/{id}/cancel
Only for checks that are pending or in_progress (not in_review). The link stops working and the check is never charged.
Auth: Secret key (ais_live_ / ais_test_)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
Idempotency-Key | header | string | No | Any unique string (a UUID is ideal). Retrying with the same key and body within 24 hours returns the first response. Up to 255 characters. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | Verification |
| 401 | Missing or invalid key | Error |
| 404 | Not found | Error |
| 409 | Not possible in the current state, or idempotency conflict | Error |
curl -X POST https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/cancel \
-H "Authorization: Bearer $AIS_SECRET_KEY"{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "canceled",
"result": null,
"reference": "order_1234",
"metadata": {
"plan": "gold"
},
"customer": {
"email": "jane@example.com",
"name": "Jane Citizen",
"phone": null
},
"document": null,
"checks": null,
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"redirect_url": null,
"report_url": null,
"source": "api",
"created_at": 1763540000,
"started_at": null,
"completed_at": 1763540600,
"expires_at": 1764144800
}Create a new client token
POST/api/v1/verifications/{id}/client_token
Client tokens last one hour. Mint a fresh one for an open check before mounting the SDK again.
Auth: Secret key (ais_live_ / ais_test_)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Created | ClientToken |
| 401 | Missing or invalid key | Error |
| 404 | Not found | Error |
| 409 | Not possible in the current state, or idempotency conflict | Error |
curl -X POST https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/client_token \
-H "Authorization: Bearer $AIS_SECRET_KEY"{
"object": "client_token",
"verification": "cmi4x0abc0001xyz",
"client_token": "ais_ct_eyJ2IjoiY21pNHgwYWJjMDAwMXh5eiJ9.EXAMPLE_SIGNATURE",
"expires_at": 1763543600
}Download the PDF report
GET/api/v1/verifications/{id}/report.pdf
Available once the check has completed (approved or declined). Test-mode reports are built from simulated data and marked TEST.
Auth: Secret key (ais_live_ / ais_test_)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | string (binary) | |
| 401 | Missing or invalid key | Error |
| 404 | Not found | Error |
| 409 | Not possible in the current state, or idempotency conflict | Error |
curl https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/report.pdf \
-H "Authorization: Bearer $AIS_SECRET_KEY" \
-o verification-report.pdfContent-Type: application/pdf
Content-Disposition: attachment; filename="...pdf"
<binary PDF>Account
Plan and credit.
Plan, credit balance and included checks
GET/api/v1/account
Auth: Secret key (ais_live_ / ais_test_)
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | Account |
| 401 | Missing or invalid key | Error |
curl https://portal.australianidentitysolutions.com.au/api/v1/account \
-H "Authorization: Bearer $AIS_SECRET_KEY"{
"object": "account",
"id": "cmorgexample0001",
"name": "Example Pty Ltd",
"livemode": false,
"plan": "business",
"currency": "aud",
"credit_balance": 42.5,
"price_per_check": 0,
"included_checks": {
"per_month": 25,
"used": 3,
"remaining": 22
}
}SDK (browser) endpoints
Browser endpoints used by the front-end SDK (publishable key or client token).
Create an anonymous check from a browser (publishable key)
POST/api/v1/sdk/verifications
Used by the SDK in publishable-key mode. If the account lists Allowed domains, the request Origin must be one of them. Returns no results, ever.
Auth: Publishable key (ais_pk_live_ / ais_pk_test_)
Request body (JSON, every field optional)
| Field | Type | Description |
|---|---|---|
reference | string | Up to 200 characters. |
metadata | Metadata | Up to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total. |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Created | SdkVerification |
| 401 | Missing or invalid key | Error |
| 402 | Not enough credit | Error |
| 403 | Origin not allowed | Error |
| 429 | Rate limited | Error |
# Normally called for you by AIS.mount({ publishableKey }) in the browser.
curl https://portal.australianidentitysolutions.com.au/api/v1/sdk/verifications \
-H "Authorization: Bearer ais_pk_test_YOUR_TEST_PUBLISHABLE_KEY" \
-H "Content-Type: application/json" \
-H "Origin: https://www.example.com.au" \
-d '{ "reference": "order_1234" }'{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "pending",
"result": null,
"reference": "order_1234",
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"client_token": "ais_ct_eyJ2IjoiY21pNHgwYWJjMDAwMXh5eiJ9.EXAMPLE_SIGNATURE",
"client_token_expires_at": 1763543600,
"embeddable": true
}Status of the check a client token is for
GET/api/v1/sdk/verification
Auth: Client token (ais_ct_)
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | SdkVerification |
| 401 | Missing or invalid key | Error |
| 404 | Not found | Error |
# Normally called for you by the SDK while the check is open.
curl https://portal.australianidentitysolutions.com.au/api/v1/sdk/verification \
-H "Authorization: Bearer ais_ct_eyJ2IjoiY21pNHgwYWJjMDAwMXh5eiJ9.EXAMPLE_SIGNATURE"{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "in_progress",
"result": null,
"reference": "order_1234",
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"embeddable": true
}The verification object
Returned by create, retrieve, list and cancel, and sent as data.object in every webhook. document and checks are null until the check has run.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
object | "verification" | Yes | |
livemode | boolean | Yes | |
status | string | Yes | pending: created, not opened. in_progress: customer started. in_review: manual review, a result follows. completed: finished (see result). expired/abandoned/canceled: ended without a result, not charged. One of: pending, in_progress, in_review, completed, expired, abandoned, canceled. |
result | string or null | Yes | One of: approved, declined, or null. |
reference | string or null | No | |
metadata | Metadata | No | Up to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total. |
customer | object | No | |
customer.email | string or null | No | |
customer.name | string or null | No | |
customer.phone | string or null | No | |
document | object or null | No | Present once the check has run. |
document.type | string or null | No | One of: passport, driving_licence, id_card, residence_permit, other, or null. |
document.country | string or null | No | Example: "Australia". |
document.country_code | string or null | No | ISO 3166-1 alpha-3 Example: "AUS". |
checks | object or null | No | Present once the check has run. |
checks.document | object | No | |
checks.document.status | string | No | One of: passed, failed, review, not_run. |
checks.face_match | object | No | |
checks.face_match.status | string | No | One of: passed, failed, review, not_run. |
checks.face_match.score | number or null | No | Similarity 0-100 |
checks.liveness | object | No | |
checks.liveness.status | string | No | One of: passed, failed, review, not_run. |
checks.aml | object | No | |
checks.aml.status | string | No | One of: passed, failed, review, not_run. |
checks.aml.hits | integer or null | No | |
verification_url | string (uri) | Yes | The customer link (our branded page). |
redirect_url | string or null | No | |
report_url | string or null | No | PDF report (needs your secret key), once completed. |
source | string | No | One of: api, sdk, widget, dashboard. |
created_at | integer | Yes | Unix seconds |
started_at | integer or null | No | |
completed_at | integer or null | No | |
expires_at | integer | Yes | Unix seconds; links last 7 days |
The create response also includes client_token (for the SDK, valid 1 hour, this check only) and client_token_expires_at (Unix seconds).
{
"id": "cmi4x0abc0001xyz",
"object": "verification",
"livemode": false,
"status": "completed",
"result": "approved",
"reference": "order_1234",
"metadata": {
"plan": "gold"
},
"customer": {
"email": "jane@example.com",
"name": "Jane Citizen",
"phone": null
},
"document": {
"type": "driving_licence",
"country": "Australia",
"country_code": "AUS"
},
"checks": {
"document": {
"status": "passed"
},
"face_match": {
"status": "passed",
"score": 96.8
},
"liveness": {
"status": "passed"
},
"aml": {
"status": "passed",
"hits": 0
}
},
"verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
"redirect_url": null,
"report_url": "https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/report.pdf",
"source": "api",
"created_at": 1763540000,
"started_at": 1763540060,
"completed_at": 1763540240,
"expires_at": 1764144800
}Statuses and checks
| status | Meaning | Charged |
|---|---|---|
pending | Created, not opened yet. | No |
in_progress | The customer has started. | No |
in_review | Sent to manual review. A final result follows. | Not yet |
completed | Finished. result is approved or declined. | Yes (live) |
expired | The link ran out (links last 7 days). | No |
abandoned | The customer left without finishing. | No |
canceled | You cancelled it with the cancel endpoint. | No |
resultisapprovedordeclinedwhen status iscompleted, otherwisenull. Filter lists with?result=approved.- Each entry in
checks(document,face_match,liveness,aml) has a status ofpassed,failed,reviewornot_run.face_match.scoreis a 0 to 100 similarity;aml.hitsis the number of PEP or sanctions matches. document.typeispassport,driving_licence,id_card,residence_permitorother;country_codeis ISO 3166-1 alpha-3, for exampleAUS.sourcetells you where the check was created:api,sdk,widgetordashboard.
Webhook events
Seven event types, each signed with AIS-Signature. The full list, the envelope, signature code and the retry schedule are in the webhooks guide.