API reference · v1.0.0 · OpenAPI 3.1

KYC API reference for Australian businesses

Every endpoint of the Australian Identity Solutions identity verification API, with parameters, example requests and responses, and error codes. Generated from our OpenAPI spec.

Overview

Base URLhttps://portal.australianidentitysolutions.com.au
Versionv1 (paths start /api/v1)
FormatJSON request and response bodies, snake_case field names, HTTPS only
Spechttps://portal.australianidentitysolutions.com.au/api/v1/openapi.json

The live spec is public. Import it into Postman, Insomnia or a code generator:

Download the OpenAPI spec
curl https://portal.australianidentitysolutions.com.au/api/v1/openapi.json -o ais-openapi-v1.json

Authentication

Server endpoints take your secret key as a Bearer token:

Header
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

TopicHow it works
Request-IdEvery response has a Request-Id header (req_...). Quote it if you contact us.
TimestampsUnix seconds (created_at, started_at, completed_at, expires_at).
IdempotencySend 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.
PaginationLists 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 limits100 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 sizeRequest bodies up to 16 KB.
MetadataUp to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total.
ChargingA 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 body (example values)
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "customer.email: must be a valid email address",
    "param": "customer.email"
  }
}

Error types

typeHTTP statusMeaning
invalid_request_error400, 404, 409, 413Something about the request is wrong (bad parameter, unknown id, wrong state).
authentication_error401Missing, invalid or revoked key, or the wrong kind of key for the endpoint.
permission_error403The browser origin is not in your Allowed domains.
billing_error402Live mode: your credit does not cover the check.
idempotency_error400, 409A problem with the Idempotency-Key header.
rate_limit_error429Too many requests. Wait for Retry-After seconds.
api_error500Something went wrong on our side. Safe to retry.

Error codes

codeStatusMeaning
parameter_invalid400A field failed validation. param names it, for example customer.email.
invalid_json400The body is not valid JSON.
body_too_large413The body is over 16 KB.
missing_api_key401No Authorization (or x-api-key) header.
invalid_api_key401The key is invalid or has been revoked.
secret_key_required401This endpoint needs a secret key (ais_live_ or ais_test_).
wrong_key_type401This endpoint needs a publishable key (ais_pk_live_ or ais_pk_test_).
invalid_client_token401The client token is invalid or has expired. Create a new one.
insufficient_credit402Live mode: top up, or wait for included checks to renew.
origin_not_allowed403Add the website to Allowed domains in the dashboard.
resource_missing404No verification with that id in this account and mode.
verification_not_cancelable409Only pending or in_progress checks can be cancelled (not in_review or finished).
verification_not_open409Client tokens can only be created for open checks.
report_not_ready409The PDF is available once the check is completed (approved or declined).
idempotency_key_invalid400Idempotency-Key must be 1 to 255 printable ASCII characters.
idempotency_key_reused400That key was already used with a different request. Use a new key.
idempotency_key_in_use409A request with that key is still running. Retry shortly.
rate_limited429Wait for the number of seconds in Retry-After.
internal_error500Retry. 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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNoAny 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)

FieldTypeDescription
customerobject
customer.emailstring (email)Up to 254 characters.
customer.namestringUp to 200 characters.
customer.phonestringUp to 32 characters. Example: "+61400000000".
referencestringYour own id for this check (order, customer or case number). Up to 200 characters.
metadataMetadataUp to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total.
send_emailbooleanDefault: true when customer.email is given.
redirect_urlstring (uri)https only. Where we send the customer after they finish (we add verification_id, status and result).

Responses

StatusDescriptionBody
201CreatedVerificationWithClientToken
400Invalid requestError
401Missing or invalid keyError
402Not enough creditError
409Not possible in the current state, or idempotency conflictError
429Rate limitedError
500Server errorError
Example request (example values)
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
  }'
Response 201 (example values)
{
  "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

NameInTypeRequiredDescription
limitqueryintegerNo1 to 100. Default 20.
starting_afterquerystringNoA verification id; returns the items after it.
statusquerystringNopending: 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.
resultquerystringNoOne of: approved, declined.
referencequerystringNoUp to 200 characters.
created[gte]queryinteger or string (date-time)NoUnix seconds or ISO 8601.
created[lte]queryinteger or string (date-time)NoUnix seconds or ISO 8601.

Responses

StatusDescriptionBody
200OKVerificationList
400Invalid requestError
401Missing or invalid keyError
429Rate limitedError
Example request (example values)
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"
Response 200 (example values)
{
  "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

NameInTypeRequiredDescription
idpathstringYes

Responses

StatusDescriptionBody
200OKVerification
401Missing or invalid keyError
404Not foundError
429Rate limitedError
Example request (example values)
curl https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz \
  -H "Authorization: Bearer $AIS_SECRET_KEY"
Response 200 (example values)
{
  "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

NameInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoAny 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

StatusDescriptionBody
200OKVerification
401Missing or invalid keyError
404Not foundError
409Not possible in the current state, or idempotency conflictError
Example request (example values)
curl -X POST https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/cancel \
  -H "Authorization: Bearer $AIS_SECRET_KEY"
Response 200 (example values)
{
  "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

NameInTypeRequiredDescription
idpathstringYes

Responses

StatusDescriptionBody
201CreatedClientToken
401Missing or invalid keyError
404Not foundError
409Not possible in the current state, or idempotency conflictError
Example request (example values)
curl -X POST https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/client_token \
  -H "Authorization: Bearer $AIS_SECRET_KEY"
Response 201 (example values)
{
  "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

NameInTypeRequiredDescription
idpathstringYes

Responses

StatusDescriptionBody
200PDFstring (binary)
401Missing or invalid keyError
404Not foundError
409Not possible in the current state, or idempotency conflictError
Example request (example values)
curl https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/report.pdf \
  -H "Authorization: Bearer $AIS_SECRET_KEY" \
  -o verification-report.pdf
Response 200 (example values)
Content-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

StatusDescriptionBody
200OKAccount
401Missing or invalid keyError
Example request (example values)
curl https://portal.australianidentitysolutions.com.au/api/v1/account \
  -H "Authorization: Bearer $AIS_SECRET_KEY"
Response 200 (example values)
{
  "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)

FieldTypeDescription
referencestringUp to 200 characters.
metadataMetadataUp to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total.

Responses

StatusDescriptionBody
201CreatedSdkVerification
401Missing or invalid keyError
402Not enough creditError
403Origin not allowedError
429Rate limitedError
Example request (example values)
# 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" }'
Response 201 (example values)
{
  "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

StatusDescriptionBody
200OKSdkVerification
401Missing or invalid keyError
404Not foundError
Example request (example values)
# 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"
Response 200 (example values)
{
  "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.

FieldTypeRequiredDescription
idstringYes
object"verification"Yes
livemodebooleanYes
statusstringYespending: 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.
resultstring or nullYesOne of: approved, declined, or null.
referencestring or nullNo
metadataMetadataNoUp to 20 string key/values. Keys up to 40 characters (letters, digits, _ . - :), values up to 500, 4 KB in total.
customerobjectNo
customer.emailstring or nullNo
customer.namestring or nullNo
customer.phonestring or nullNo
documentobject or nullNoPresent once the check has run.
document.typestring or nullNoOne of: passport, driving_licence, id_card, residence_permit, other, or null.
document.countrystring or nullNoExample: "Australia".
document.country_codestring or nullNoISO 3166-1 alpha-3 Example: "AUS".
checksobject or nullNoPresent once the check has run.
checks.documentobjectNo
checks.document.statusstringNoOne of: passed, failed, review, not_run.
checks.face_matchobjectNo
checks.face_match.statusstringNoOne of: passed, failed, review, not_run.
checks.face_match.scorenumber or nullNoSimilarity 0-100
checks.livenessobjectNo
checks.liveness.statusstringNoOne of: passed, failed, review, not_run.
checks.amlobjectNo
checks.aml.statusstringNoOne of: passed, failed, review, not_run.
checks.aml.hitsinteger or nullNo
verification_urlstring (uri)YesThe customer link (our branded page).
redirect_urlstring or nullNo
report_urlstring or nullNoPDF report (needs your secret key), once completed.
sourcestringNoOne of: api, sdk, widget, dashboard.
created_atintegerYesUnix seconds
started_atinteger or nullNo
completed_atinteger or nullNo
expires_atintegerYesUnix 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).

A completed verification (example values)
{
  "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

statusMeaningCharged
pendingCreated, not opened yet.No
in_progressThe customer has started.No
in_reviewSent to manual review. A final result follows.Not yet
completedFinished. result is approved or declined.Yes (live)
expiredThe link ran out (links last 7 days).No
abandonedThe customer left without finishing.No
canceledYou cancelled it with the cancel endpoint.No
  • result is approved or declined when status is completed, otherwise null. Filter lists with ?result=approved.
  • Each entry in checks (document, face_match, liveness, aml) has a status of passed, failed, review or not_run. face_match.score is a 0 to 100 similarity; aml.hits is the number of PEP or sanctions matches.
  • document.type is passport, driving_licence, id_card, residence_permit or other; country_code is ISO 3166-1 alpha-3, for example AUS.
  • source tells you where the check was created: api, sdk, widget or dashboard.
Australian Government DVS checks are included on every plan at no extra cost. API v1 has no separate DVS field.

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.