Quickstart · About 15 minutes

Your first verification in five steps

Everything here runs in test mode on the Growth plan, so the test checks are free of charge. Swap in live keys at the end and the same code runs real checks.

1. Sign up and choose the Growth plan

Create an account and choose the Growth plan ($299/month, 75 checks included). API access, test keys and test mode are included with the Growth plan only; Pay As You Go and Business accounts use the dashboard without API access. Test checks are free of charge. Everything below lives in the dashboard under Developers, API Keys and Webhooks.

2. Create test keys

Open API Keys and create a key in test mode. The prefix tells you what each key is for:

  • ais_test_: test secret key, for your server. Shown once, so store it in an environment variable (AIS_SECRET_KEY in the examples).
  • ais_pk_test_: test publishable key, safe in a web page. It can start a check but can never read results.
  • Live keys use ais_live_ and ais_pk_live_. Test keys only ever see test checks, and live keys only see live checks.
Never put a secret key in a browser, mobile app or public repo. The SDK refuses secret keys and tells you to revoke one if you try.

3. Create a verification

From your server, POST to /api/v1/verifications. Every field is optional. If you pass customer.email we email the customer their link unless you set send_email to false (do that when you show the check in your own page).

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
}

Save id against your customer. You now have two ways to show the check: send the customer verification_url, or embed it with the client_token (valid for one hour, for this check only). If the token expires, mint another with POST /api/v1/verifications/{id}/client_token.

4. Show the check

Embedding needs your site in Allowed domains. For local testing add http://localhost:3000 (plain http is only accepted for localhost and 127.0.0.1). Then give the browser the client token from your server and mount the SDK:

index.html
<!-- Where the check appears -->
<div id="ais-verify"></div>

<script src="https://portal.australianidentitysolutions.com.au/sdk/v1/ais.js"></script>
<script>
  // 1. Ask YOUR server for a client token (see "Server side" below).
  fetch("/start-verification", { method: "POST" })
    .then(function (r) { return r.json(); })
    .then(function (data) {
      // 2. Mount the check with it. Never put a secret key in a web page.
      AIS.mount({
        clientToken: data.client_token,   // ais_ct_..., valid for 1 hour
        container: "#ais-verify",
        mode: "inline",                   // or "modal"
        onComplete: function (r) {
          // r = { id, status, result }. Confirm on your server before acting on it.
          window.location = "/verified?id=" + encodeURIComponent(r.id);
        },
        onError: function (e) { console.error(e.code, e.message); }
      });
    });
</script>

Your server route that returns the token, in your language:

server.mjs

// Node 18+ with Express. Keep the secret key in an environment variable.
import express from "express";

const app = express();
app.use(express.json());

// Your page calls this, then passes client_token to AIS.mount().
app.post("/start-verification", async (req, res) => {
  const user = req.user; // however your app knows who is signed in
  const r = await fetch("https://portal.australianidentitysolutions.com.au/api/v1/verifications", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AIS_SECRET_KEY}`, // ais_test_... or ais_live_...
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer: { email: user.email, name: user.name },
      reference: String(user.id), // your own id, returned in every webhook
      send_email: false,          // the check is embedded, so don't email a link
    }),
  });
  const v = await r.json();
  if (!r.ok) return res.status(r.status).json({ error: v.error.message });

  // Save v.id against the user, then give the browser ONLY the client token.
  res.json({ client_token: v.client_token });
});

app.listen(3000);

Because this is a test check, the frame shows a clearly marked TEST page. Choose Approve, Decline, Needs review or Abandon. No ID or selfie is taken. Prefer no embed? Open verification_url in a browser instead.

5. Receive the webhook

  1. In Webhooks, add an endpoint in test mode with your HTTPS URL and choose the events you want (or all of them).
  2. Copy the signing secret (whsec_...) into AIS_WEBHOOK_SECRET.
  3. Press Send test event to check your receiver, then complete a test check for the real thing.

webhook.mjs

// Node + Express. Use the RAW body: re-serialised JSON will not match the signature.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.AIS_WEBHOOK_SECRET; // the full secret, including "whsec_"

function verify(rawBody, header) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((p) => p.split("=", 2))
  );
  const t = Number(parts.t);
  if (!t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // 5-minute tolerance
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest("hex");
  return parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

app.post("/webhooks/ais", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("AIS-Signature"))) return res.status(400).send("bad signature");

  const event = JSON.parse(raw);
  res.sendStatus(200); // reply fast, then do the work

  if (await alreadyProcessed(event.id)) return; // de-duplicate on the event id
  const v = event.data.object; // same shape as GET /api/v1/verifications/{id}
  if (event.type === "verification.completed") { /* approved: v.reference, v.checks ... */ }
  if (event.type === "verification.failed")    { /* declined */ }
});

app.listen(3000);

C#, Java and Next.js versions are on the webhooks guide.

Event body (example values)
{
  "id": "evt_5c1e9a7b3f2d4e6a8b0c1d2e",
  "object": "event",
  "type": "verification.completed",
  "created": 1763540240,
  "livemode": false,
  "data": {
    "object": {
      "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
    }
  }
}

Reply 2xx within 10 seconds and do slow work afterwards. Treat the webhook as the source of truth: onComplete in the browser is only a signal to refresh. Full details in the webhooks guide.

Go live

  • Live keys: create ais_live_ (server) and, if you embed with a publishable key, ais_pk_live_. Swap them into your environment variables. Nothing else in your code changes.
  • Live webhook endpoint: test and live endpoints are separate. Add a live one (up to 5 endpoints per account) and store its own secret.
  • Allowed domains: add your production origin, for example https://www.example.com.au, or https://*.example.com.au for every subdomain. Once you list domains, publishable keys only start checks from those sites.
  • redirect_url (link flow): when customers open the link directly rather than in your page, pass an https redirect_url and we send them back with verification_id, status and result added to the query string.
  • Credit: live checks need enough credit (or included Growth plan checks) when you create them, otherwise the API returns 402 insufficient_credit. A live check is charged once, when it completes.