# ZetaID documentation

Source: https://docs.zetaid.com/

ZetaID checks that a person is who they say they are: an identity document,
a selfie or a hand-movement check, sanctions screening, a wallet proof. You
start a check from your server, send the person to the ZetaID verification
page, and receive the result on your server.

## How a verification works

1. **Your server creates a verification** with your API key
   (`POST /api/v1/verifications`). ZetaID answers with a `verification_id`
   and a `url`.
2. **The person opens the `url`**: the ZetaID verification page walks them
   through the steps your key asks for (for example: photograph the ID card,
   then a short selfie). On a computer without a camera, the page offers to
   continue on a phone.
3. **ZetaID checks what was captured** and decides: `verified`, `rejected` or
   `needs_manual_review`.
4. **Your server gets the result**: a signed webhook to the URL you set on the
   key, and on request with `GET /api/v1/verifications/{id}`.
5. **The person comes back** to your `return_url`, and your site continues
   with what your server now knows.

Your API key never leaves your server. The person's browser only ever talks
to the ZetaID verification page.

  - [Quickstart](https://docs.zetaid.com/quickstart/): Your first verification in five steps.
  - [Integrate a website](https://docs.zetaid.com/guides/website-integration/): A complete, safe integration, step by step.
  - [API reference](https://docs.zetaid.com/reference/api/): The two calls, their fields and answers.
  - [Agent skill](https://docs.zetaid.com/agents/agent-skill/): Let your coding agent build the integration.

## What you need

  **An operator console login**
    We set up your organization and send you the login for the operator
    console. There you create API keys, choose what each key checks, and see
    every verification.
  
  **A server**
    Any backend that can make HTTPS requests and receive one: Node.js, PHP,
    Python, Java, Go, … The API is not meant to be called from a browser or
    a mobile app.

---

# Quickstart

Source: https://docs.zetaid.com/quickstart/

1. **Create an API key.** In the operator console, open **API keys** →
   **New API key**. Give it a name (for example `Shop – production`) and the
   URL where your server receives webhooks. The console shows the **API key**
   (`vk_live_…`) and the **webhook signing secret** (`whsec_…`) exactly once:
   store both in your server's secret store.

2. **Choose what the key checks.** In the same dialog, or later with **Edit
   key**, pick the steps of the flow, for example *document* then
   *liveness*. See [Configure a key](https://docs.zetaid.com/guides/configure-a-key/).

3. **Create a verification from your server.**

   ```sh
   curl -X POST https://verify.zetaid.com/api/v1/verifications \
     -H "X-SDK-Key: $ZETAID_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"return_url": "https://shop.example/checkout/verified?order=A-17",
          "extra_data": {"order_id": "A-17"}}'
   ```

   ```json
   {
     "verification_id": "3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
     "url": "https://verify.zetaid.com/?verification_id=3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
     "flow": ["document", "liveness"],
     "due_at": "2026-11-02T10:15:00Z",
     "expires_at": "2027-01-30T10:15:00Z"
   }
   ```

4. **Send the person to `url`.** Redirect their browser to it. When they are
   done, the page sends them back to your `return_url`.

5. **Receive the result.** ZetaID posts a `verification.completed` webhook to
   your key's URL. Check its signature, then act on `status`:

   ```json
   {
     "event": "verification.completed",
     "verification_id": "3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
     "status": "verified",
     "reason_code": null,
     "export": { "personal_info": { "first_name": "ERIKA", "last_name": "MUSTERMANN", "date_of_birth": "1983-08-12" } },
     "extra_data": { "order_id": "A-17" },
     "completed_at": "2026-11-01T10:19:42Z"
   }
   ```

   You can also read the same fields at any time with
   `GET /api/v1/verifications/{verification_id}`.

> **Server side only**
  The API key identifies your organization and is billed to it. Keep it on
  your server. A request to the API from a web page is refused
  (`403 SERVER_SIDE_ONLY`).

Next: [integrate a website](https://docs.zetaid.com/guides/website-integration/) end to end, with
signature checks, the return page and expired links.

---

# API keys

Source: https://docs.zetaid.com/guides/api-keys/

An API key does two things: it authenticates your server's requests, and it
carries the settings of every verification created with it (which steps the
person goes through, how long data is kept, where webhooks go).

## Create a key

1. Sign in to the **operator console** with your organization's main login
   (only main logins see **API keys**).
2. Open **API keys** → **New API key**.
3. Enter a **name** that says where the key is used, for example
   `Shop – production` or `Hotel check-in – staging`.
4. Enter the **webhook URL**: the HTTPS address on your server that receives
   results (you can add or change it later).
5. Choose the flow and the other settings ([Configure a key](https://docs.zetaid.com/guides/configure-a-key/)).
6. Create the key. The console shows two values **once**:
   - the **API key** (`vk_live_…`), sent with every API request;
   - the **webhook signing secret** (`whsec_…`), used to check that webhooks
     really come from ZetaID ([Get the result](https://docs.zetaid.com/guides/get-the-result/#check-the-signature)).

Copy both into your server's secret store (environment variables, a vault,
your platform's secret manager). ZetaID keeps only a fingerprint of the API
key and cannot show it again; if it is lost, create a new key.

## Use a key

Send the key in the `X-SDK-Key` header of every API request:

```http
POST /api/v1/verifications HTTP/1.1
Host: verify.zetaid.com
X-SDK-Key: vk_live_8c1f…
Content-Type: application/json
```

A missing, wrong or deactivated key gets `401 SDK_KEY_INVALID`.

> **Never in a browser or an app**
  Anyone who has the key can create verifications billed to your
  organization and read results. Don't put it in JavaScript that runs in the
  browser, in a mobile app, or in a repository. The API refuses requests that
  come from a web page (`403 SERVER_SIDE_ONLY`).

## One key per use

Create a separate key for every site, app or environment. Each key has its own
flow, retention and webhook URL, and the operator console shows which key
created each verification. A test environment gets its own key with its own
webhook URL.

## Replace a key

To replace a key (a suspected leak, a staff change):

1. Create a new key with the same settings.
2. Deploy it to your server.
3. In **API keys**, deactivate the old key. Verifications that are already
   running continue; new requests with the old key are refused.

A key that never created a verification can be deleted; any other key can
only be deactivated, so its verifications keep their history.

## The webhook signing secret

Every key has its own signing secret. **Rotate signing secret** on the key
replaces it and shows the new one once; from that moment ZetaID signs this
key's webhooks (including retries of earlier ones) with the new secret, so
update your server right away.

Keys created before signing secrets existed show **Shared platform
signature**: use **Create signing secret** on them to give them their own.

---

# Configure a key

Source: https://docs.zetaid.com/guides/configure-a-key/

Every verification takes its settings from the key that created it, as they
were at that moment. You change them in the operator console: **API keys** →
the key → **Edit key**. A change applies to verifications created afterwards;
running ones keep what they started with.

## Flow (module order)

The steps the person goes through, in this order. Click the modules in the
order you want them; the number on each shows its position, and a second
click removes it. An empty flow uses the default: `document`, then
`liveness`.

| Module | What the person does | What you get |
|---|---|---|
| `document` | Photographs a passport, ID card, residence permit or driving licence (both sides where needed). | Name, date of birth, nationality, document number and expiry, read from the document and cross-checked. |
| `liveness` | Takes a short selfie. | Proof that a live person was present, matched against the document photo. |
| `palm_liveness` | Moves an open hand to a few dots on the screen (Human check). | Proof that a live person, not a bot, did it — no face, no document. |
| `terms` | Accepts your terms. | The acceptance, with time. |
| `form_data` | Fills in a short form (for example an address). | The values, in the result's `contact_info`. |
| `email` | Confirms an email address with a code. | The confirmed address. |
| `phone` | Confirms a phone number with a code by SMS. | The confirmed number. |
| `aml` | Nothing: runs automatically after the other steps. | Sanctions screening of the name read from the document. |
| `nfc` | Holds their passport or ID card to their phone so the chip can be read. | The chip's data, authenticated by the issuing state. Available on request. |
| `wallet` | Shares a proof from their digital identity wallet. | The requested attributes, for example *over 18*. Needs a registration with us first. |

A flow needs at least one step the person does; `aml` alone is not a flow.
The order matters: put `document` before `liveness` so the selfie can be
matched to the document photo.

You can also send a different `flow` with a single verification
([Create a verification](https://docs.zetaid.com/guides/create-a-verification/)); the key's flow is
the default.

## Keep images for (days)

How long the captured images (document photos, selfie) are kept. Default 90.
After that they are deleted; the verification's outcome stays.

## Keep personal data for (days)

How long the personal data the check produced (names, dates, numbers, the
result's `export`) is kept. It must be at least as long as the images, and at
most 3,650 days (10 years). New keys start with the same value as the images.

This is your decision: keep what your own obligations require (for example a
hotel's guest register) and no more. After the deadline the verification
keeps only its outcome — `GET /api/v1/verifications/{id}` then answers with
`status` and `export: null`.

## Due days

How long the link (`url`) works before the verification expires without a
result. Default 1 day. Expired verifications send a
[`verification.expired`](https://docs.zetaid.com/reference/webhooks/#verificationexpired) webhook.

Once the person has started, a verification also expires after 24 hours
without any input (reason `ABANDONED`). To change that window, set
`abandon_after_hours` in the key's raw config JSON (`0` turns it off).

## Policies

Leave these empty to use the platform defaults; change them only when you
know why.

- **Blur threshold** (`quality_threshold_0_10`, default 4.5): how sharp a
  document photo must be. A lower value accepts softer photos.
- **Face match distance** (`face_match_max_distance`, default 0.7): how
  close the selfie must be to the document photo. A lower value is stricter.
- **Chip face match distance** (`chip_face_match_max_distance`, default
  0.7): the same for the photo on a document's chip.
- **Gates** (`recapture_gate`, `blackout_gate`, `liveness_spoof_gate`): what
  happens when a check finds a photographed screen, a covered document or a
  spoofed selfie. `flag_review` sends the verification to manual review;
  `shadow` only records the finding.

## Image redaction

Hides parts of images (machine-readable zone and QR codes, the portrait,
specific fields) when they are shown in the operator console. The stored
images are not changed.

## Webhook URL

Where ZetaID posts this key's [webhooks](https://docs.zetaid.com/reference/webhooks/). It must be
HTTPS and answer within 20 seconds. Empty = no webhooks; read results with
`GET /api/v1/verifications/{id}` instead.

> **Note**
  Want only an *over 18* answer instead of the full identity, or results
  offered to the person's wallet? Those settings exist, but we set them up
  with you — contact us.

---

# Create a verification

Source: https://docs.zetaid.com/guides/create-a-verification/

Create one verification per person and occasion (an order, a booking, an
account sign-up), from your server, at the moment the person needs it.

```http
POST https://verify.zetaid.com/api/v1/verifications
X-SDK-Key: vk_live_…
Content-Type: application/json
```

## The request

Every field is optional; an empty body (`{}`) uses the key's settings.

| Field | Type | |
|---|---|---|
| `return_url` | string | Where the verification page sends the person when they are done. |
| `extra_data` | object | Your own reference, returned in every webhook and `GET` (for example `{"order_id": "A-17"}`). |
| `flow` | string[] | The steps for this verification only, instead of the key's flow. Module names as in [Configure a key](https://docs.zetaid.com/guides/configure-a-key/#flow-module-order). |
| `module_overrides` | object | Settings for single modules of this verification, for example prefilled form values (below). |

**`return_url`**: the page shows "Continue" and moves on after a few
seconds. ZetaID adds nothing to the URL, so put your own reference in it
(`https://shop.example/checkout/verified?order=A-17`). Treat the return as
"the person is back", never as "the person is verified": the result comes
from your server ([Get the result](https://docs.zetaid.com/guides/get-the-result/)).

**`extra_data`**: a small JSON object of your own identifiers. Don't put
personal data in it (no names, birth dates or email addresses) — it is
stored with the verification and sent back in every webhook.

**`module_overrides`**: for a `form_data` step, prefill values and lock the
ones the person must not change:

```json
{
  "module_overrides": {
    "form_data": {
      "values": { "booking_reference": "ABC123" },
      "locked": ["booking_reference"]
    }
  }
}
```

## The answer

`201 Created`:

```json
{
  "verification_id": "3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
  "url": "https://verify.zetaid.com/?verification_id=3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
  "flow": ["document", "liveness"],
  "due_at": "2026-11-02T10:15:00Z",
  "expires_at": "2027-01-30T10:15:00Z"
}
```

| Field | |
|---|---|
| `verification_id` | Store it with your order, booking or account. |
| `url` | The link for the person. Use it as it is; it can be on your own branded host if we set one up for you. |
| `flow` | The steps this verification will go through. |
| `due_at` | Until when the link works. Afterwards the verification expires (`verification.expired`). |
| `expires_at` | When the captured images will be deleted (the key's image retention). |

## Examples

  **Node.js**
```js
const res = await fetch("https://verify.zetaid.com/api/v1/verifications", {
  method: "POST",
  headers: { "X-SDK-Key": process.env.ZETAID_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    return_url: `https://shop.example/checkout/verified?order=${order.id}`,
    extra_data: { order_id: order.id },
  }),
});
if (!res.ok) throw new Error(`ZetaID ${res.status}: ${(await res.json()).error?.code}`);
const { verification_id, url } = await res.json();
```
  
  **Python**
```python

res = requests.post(
    "https://verify.zetaid.com/api/v1/verifications",
    headers={"X-SDK-Key": os.environ["ZETAID_API_KEY"]},
    json={
        "return_url": f"https://shop.example/checkout/verified?order={order.id}",
        "extra_data": {"order_id": order.id},
    },
    timeout=20,
)
res.raise_for_status()
verification = res.json()  # verification["verification_id"], verification["url"]
```
  
  **PHP**
```php
$ch = curl_init('https://verify.zetaid.com/api/v1/verifications');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ['X-SDK-Key: ' . getenv('ZETAID_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'return_url' => 'https://shop.example/checkout/verified?order=' . urlencode($order->id),
        'extra_data' => ['order_id' => $order->id],
    ]),
]);
$verification = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 201 on success
```
  

## When it fails

| Status | `error.code` | What to do |
|---|---|---|
| 401 | `SDK_KEY_INVALID` | The key is missing, wrong or deactivated. |
| 402 | `CREDITS_EXHAUSTED` | Your prepaid balance is below zero. Top up in the operator console (**Billing**). |
| 403 | `SERVER_SIDE_ONLY` | The request came from a web page. Call the API from your server. |
| 422 | `FLOW_INVALID` | An unknown module in `flow`, or no step the person does. |
| 503 | `SYSTEM_TEMPORARILY_UNAVAILABLE` | Checks that analyse images can't start right now. Retry after a short wait. |

All errors: [Errors](https://docs.zetaid.com/reference/errors/).

> **Note**
  Create the verification when the person is about to start it, not in
  advance: the link has a deadline (`due_at`). If it expires, create a new
  verification.

---

# Send the person to the verification page

Source: https://docs.zetaid.com/guides/send-the-user/

The `url` from [Create a verification](https://docs.zetaid.com/guides/create-a-verification/) opens
the ZetaID verification page. It asks for the camera, guides the person
through the steps of the flow, and shows them how it went.

## On a website

Redirect the browser to `url` in the same tab:

```js
res.redirect(303, verification.url);
```

or show a button that links to it. Opening it in a new tab works too; the
person then returns in that tab.

**On a computer**, the page offers to continue on a phone: it shows a QR
code (and can email the link) so the person can photograph the document
with the phone's camera. Your site doesn't need to do anything for that.

**In a shop or at a front desk**, you can show `url` as a QR code that the
customer scans with their own phone.

> **No iframes**
  Don't embed the page in an `<iframe>`. Camera access, the phone hand-over
  and wallet requests need the page to be the top-level page in the
  browser.

## In a mobile app

Open `url` in the system browser or an in-app browser tab (`SFSafariViewController`
on iOS, Custom Tabs on Android), not in a plain WebView: a WebView often has
no camera permission. Use your app's link (universal link or app link) as the
`return_url` to come back into the app.

## Coming back

When the person is done, the page shows "Continue" and opens your
`return_url` after a few seconds. ZetaID adds no parameters to it — your
own reference in the URL tells you which order or booking it was.

The return only tells you the person is back. The verification may still be
running (checks usually take seconds) or waiting for a manual review. Your
return page should show what your **server** knows:

- the result has arrived (webhook) → continue or explain;
- not yet → show "We're checking your documents…" and look again in a few
  seconds (your server can call `GET /api/v1/verifications/{id}`).

See [Integrate a website](https://docs.zetaid.com/guides/website-integration/#3-the-return-page) for
a complete return page.

## If the person doesn't finish

The link works until `due_at` (the key's **Due days**, default 1 day). Once
started, a verification also ends after 24 hours without any input. Either
way it becomes `expired` and your server receives `verification.expired`.
To try again, create a new verification.

---

# Get the result

Source: https://docs.zetaid.com/guides/get-the-result/

There are two ways to learn how a verification went. Use both:

- **Webhooks** (recommended): ZetaID posts to your key's webhook URL as soon
  as something happens.
- **`GET /api/v1/verifications/{id}`**: your server asks whenever it needs
  to — on the return page, or to catch up after an outage.

## Webhooks

ZetaID sends a `POST` with a JSON body to the key's webhook URL:

| Event | When |
|---|---|
| `verification.completed` | The checks have decided: `verified`, `rejected` or `needs_manual_review`. Carries the result (`export`). |
| `verification.reviewed` | A manual review decided a `needs_manual_review` verification: `verified` or `rejected`. |
| `verification.expired` | The person didn't finish before the deadline, or stopped. |

```json
{
  "event": "verification.completed",
  "verification_id": "3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
  "status": "verified",
  "reason_code": null,
  "export": { "…": "see Reference → The result" },
  "extra_data": { "order_id": "A-17" },
  "completed_at": "2026-11-01T10:19:42Z"
}
```

All fields per event: [Reference → Webhooks](https://docs.zetaid.com/reference/webhooks/).

### Answer quickly

Answer with any `2xx` within 20 seconds, then do the work. Anything else (a
timeout, `4xx`, `5xx`) is retried up to 8 times over about two hours, with
growing gaps. The same delivery can therefore arrive more than once: use the
`X-Webhook-Delivery` header (or `verification_id` + `event`) to ignore
repeats.

### Check the signature

Your webhook URL is public, so anyone could post a fake "verified" to it.
Every webhook is signed with your key's **webhook signing secret**
(`whsec_…`, shown once when the key was created):

| Header | |
|---|---|
| `X-Webhook-Timestamp` | Unix time (seconds) when the delivery was sent. |
| `X-Webhook-Signature` | `sha256=` + hex HMAC-SHA256 of `timestamp + "." + raw body`, with your signing secret. |
| `X-Webhook-Event` | The event name. |
| `X-Webhook-Delivery` | The delivery's id, the same on every retry. |

Compute the HMAC over the **raw** request body exactly as received (before
any JSON parsing), compare in constant time, and refuse timestamps older
than five minutes:

  **Node.js**
```js

// rawBody: a Buffer of the request body as received (e.g. express.raw()).
export function validWebhook(secret, headers, rawBody) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"] ?? "";
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
```
  
  **Python**
```python

def valid_webhook(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
    return hmac.compare_digest("sha256=" + mac.hexdigest(), signature or "")
```
  
  **PHP**
```php
function valid_webhook(string $secret, string $ts, string $rawBody, string $sig): bool {
    if ($ts === '' || abs(time() - (int)$ts) > 300) return false;
    $expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret);
    return hash_equals($expected, $sig);
}
// $rawBody = file_get_contents('php://input');
```
  

Refuse a webhook whose signature doesn't match with `401`, and don't act on
it.

> **Keys without their own secret**
  A key created before signing secrets existed shows **Shared platform
  signature** in the operator console. Use **Create signing secret** on it
  and switch your server to that secret. Until then, don't trust its
  webhooks: treat them as a hint and read the result with `GET` instead.

## Read a verification

```http
GET https://verify.zetaid.com/api/v1/verifications/{verification_id}
X-SDK-Key: vk_live_…
```

`200 OK` with the same fields as the completion webhook, plus where the
verification stands:

```json
{
  "verification_id": "3f6c2a9e-7d41-4b8a-9c2e-5a1f0d7b3e64",
  "status": "verified",
  "terminal": true,
  "reason_code": null,
  "export": { "…": "the result, as in the webhook" },
  "extra_data": { "order_id": "A-17" },
  "created_at": "2026-11-01T10:15:00Z",
  "updated_at": "2026-11-01T10:19:42Z"
}
```

- `export` is `null` until the checks have run, and again once the key's
  personal-data retention has deleted it.
- Any key of your organization can read its verifications; another
  organization's id answers `404 VERIFICATION_NOT_FOUND`.
- Call it from your server only, and not in a tight loop: every few seconds
  while a person waits on your return page is plenty.

## What the status means

| `status` | Meaning | Your site |
|---|---|---|
| `generated` | Created; the person hasn't opened the link. | Waiting. |
| `initiated`, `in_progress` | The person is going through the steps. | Waiting. |
| `validating` | Everything is captured; the checks are running (seconds). | Waiting. |
| `verified` | Passed. | Continue. |
| `rejected` | Failed; `reason_code` says why. | Explain, offer a new attempt or another way. |
| `needs_manual_review` | A person at the organization reviews it (operator console). | Tell the person you'll confirm; wait for `verification.reviewed`. |
| `expired` | Not finished in time (`COMPLETION_TIMEOUT`) or abandoned (`ABANDONED`). | Offer to start again. |

`terminal: true` means the checks have finished. Only a manual review still
changes a `needs_manual_review` verification, to `verified` or `rejected`
(with a `verification.reviewed` webhook). Treat any other status you don't
know as "not decided".

What the `export` contains: [Reference → The result](https://docs.zetaid.com/reference/result/).

---

# Integrate a website

Source: https://docs.zetaid.com/guides/website-integration/

This guide builds the whole integration for a typical case: an online shop
that must verify a customer's identity (or age) before an order is
completed. The same shape fits a sign-up, a booking or an account recovery.

The rules that make it safe:

- **The API key and the webhook secret stay on your server.**
- **Your server decides**, from a signed webhook or its own API call — never
  from what the browser says (a return URL can be opened by anyone).
- **Every verification belongs to one of your records** (order, booking,
  account): you store the `verification_id` with it and get your reference
  back in `extra_data`.
- **Webhooks can repeat and arrive in any order**: handle them idempotently.

## What you build

| Your endpoint | Does |
|---|---|
| `POST /checkout/verify` | Creates the verification for the order and redirects the browser to it. |
| `POST /webhooks/zetaid` | Receives webhooks, checks the signature, updates the order. |
| `GET /checkout/verified` | The return page: shows what the server knows, asks ZetaID if it doesn't know yet. |

Your order record gets three fields: `verification_id`, `verification_status`
(`none`, `pending`, `verified`, `rejected`, `review`, `expired`) and the time
it was last updated.

## The example

Node.js with Express. `orders` stands for your own data access.

```js title="server.js"

const API = "https://verify.zetaid.com/api/v1";
const API_KEY = process.env.ZETAID_API_KEY;               // vk_live_…
const WEBHOOK_SECRET = process.env.ZETAID_WEBHOOK_SECRET; // whsec_…

const app = express();

async function zetaid(path, init = {}) {
  const res = await fetch(API + path, {
    ...init,
    headers: { "X-SDK-Key": API_KEY, "Content-Type": "application/json", ...init.headers },
    signal: AbortSignal.timeout(20_000),
  });
  const body = await res.json().catch(() => ({}));
  if (!res.ok) throw Object.assign(new Error(body.error?.code ?? `HTTP ${res.status}`), { status: res.status });
  return body;
}

// Map ZetaID's status onto the order.
function orderStatus(zetaidStatus) {
  switch (zetaidStatus) {
    case "verified": return "verified";
    case "rejected": return "rejected";
    case "needs_manual_review": return "review";
    case "expired": return "expired";
    default: return "pending";
  }
}
```

### 1. Start the verification

```js title="server.js"
app.post("/checkout/verify", async (req, res) => {
  const order = await orders.forSession(req);            // your session → order
  if (order.verification_status === "verified") return res.redirect(303, "/checkout/pay");

  try {
    const v = await zetaid("/verifications", {
      method: "POST",
      body: JSON.stringify({
        return_url: `https://shop.example/checkout/verified?order=${encodeURIComponent(order.id)}`,
        extra_data: { order_id: order.id },
      }),
    });
    await orders.update(order.id, { verification_id: v.verification_id, verification_status: "pending" });
    res.redirect(303, v.url);
  } catch (err) {
    // 503: checks can't start right now; 402: prepaid balance used up.
    res.status(503).send("Identity check unavailable right now. Please try again in a minute.");
  }
});
```

A new click on "verify" after an `expired` or `rejected` result simply
creates a new verification and replaces the stored `verification_id`.

### 2. Receive the webhooks

The signature is computed over the raw body, so read it raw for this route
only:

```js title="server.js"
app.post("/webhooks/zetaid", express.raw({ type: "application/json", limit: "1mb" }), async (req, res) => {
  const ts = req.get("X-Webhook-Timestamp") ?? "";
  const sig = req.get("X-Webhook-Signature") ?? "";
  const expected = "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(`${ts}.`).update(req.body).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  if (!fresh || sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString("utf8"));
  const order = await orders.get(event.extra_data?.order_id);
  // Only the order's current verification counts (an older attempt may report late).
  if (order && order.verification_id === event.verification_id) {
    await orders.update(order.id, {
      verification_status: orderStatus(event.status),
      // For verified customers, keep only what you need — e.g. the date of birth for an age check.
      date_of_birth: event.export?.personal_info?.date_of_birth ?? order.date_of_birth,
    });
  }
  res.status(204).end();  // answer fast; a repeat of the same event changes nothing
});
```

### 3. The return page

```js title="server.js"
app.get("/checkout/verified", async (req, res) => {
  const order = await orders.forSession(req);
  if (!order || order.id !== req.query.order) return res.redirect(303, "/checkout");

  // The webhook may not have arrived yet: ask ZetaID once.
  if (order.verification_status === "pending" && order.verification_id) {
    try {
      const v = await zetaid(`/verifications/${order.verification_id}`);
      await orders.update(order.id, { verification_status: orderStatus(v.status) });
      order.verification_status = orderStatus(v.status);
    } catch { /* keep pending; the page refreshes */ }
  }

  switch (order.verification_status) {
    case "verified": return res.redirect(303, "/checkout/pay");
    case "review":   return res.render("verify-review");    // "We'll confirm by email."
    case "rejected": return res.render("verify-failed");    // offer a new attempt
    case "expired":  return res.render("verify-expired");   // offer to start again
    default:         return res.render("verify-waiting");   // spinner, reload every 3 s
  }
});
```

The waiting page reloads itself (`<meta http-equiv="refresh" content="3">`)
and gives up after about a minute with "We'll email you when your check is
done". Checks normally finish within seconds.

> **Check what your server decides on**
  Your checkout must refuse to continue unless the **order** says
  `verified` — not a URL parameter, not a cookie, not the browser.

## The checklist

1. The API key and webhook secret are in your server's secret store, not in
   code, not in the browser.
2. Each verification is created by your server for one record, with your
   reference in `extra_data` and `return_url`.
3. The webhook route checks the signature on the raw body and the
   timestamp, answers `2xx` fast, and ignores repeats and late webhooks of
   older attempts.
4. The return page shows what your server knows and falls back to
   `GET /api/v1/verifications/{id}`.
5. `rejected`, `needs_manual_review` and `expired` each have a clear next
   step for the person.
6. You keep only the personal data you need, for as long as you need it —
   and set the key's retention to match ([Configure a key](https://docs.zetaid.com/guides/configure-a-key/#keep-personal-data-for-days)).

Then: [Going live](https://docs.zetaid.com/guides/going-live/).

---

# Going live

Source: https://docs.zetaid.com/guides/going-live/

- [ ] **A production key of its own**, with the production webhook URL and
      its own signing secret. Test and production never share a key.
- [ ] **The flow** asks for what you need and nothing more. Every step costs
      the person time and costs you per check.
- [ ] **Retention** (images and personal data) matches your obligations.
- [ ] **Webhook route** is HTTPS, checks every signature, answers within 20
      seconds, and handles repeats.
- [ ] **Failure paths** work: `rejected`, `needs_manual_review`, `expired`,
      the API unavailable (`503`), the prepaid balance used up (`402`).
- [ ] **Someone handles manual reviews** in the operator console
      (**Verifications**), so people aren't left waiting.
- [ ] **Your privacy notice** tells people that ZetaID performs the identity
      check on your behalf.
- [ ] **Monitoring**: alert when webhooks stop arriving or the API answers
      errors.

## During operation

- The operator console shows every verification with its steps, the images
  (as long as you keep them) and the result.
- **Billing** shows usage, invoices or your prepaid balance and top-ups.
- If you suspect a key leaked, [replace it](https://docs.zetaid.com/guides/api-keys/#replace-a-key)
  and rotate its signing secret.

---

# API reference

Source: https://docs.zetaid.com/reference/api/

**Base URL:** `https://verify.zetaid.com/api/v1` — the verification portal
of the ZetaID cloud. If we gave you another host (your own branded host, or
another region), use that one; the paths are the same.

**Authentication:** your API key in the `X-SDK-Key` header. Requests from a
web page (with an `Origin` header) are refused.

**Format:** JSON in and out, UTF-8. Times are RFC 3339 in UTC.

The OpenAPI description of these calls and the webhooks:
[/openapi.yaml](https://docs.zetaid.com/openapi.yaml).

## Create a verification

`POST /api/v1/verifications`

| Body field | Type | Required | |
|---|---|---|---|
| `return_url` | string (URL) | no | Where the person goes when done. Nothing is added to it. |
| `extra_data` | object | no | Your own reference; returned in webhooks and `GET`. No personal data. |
| `flow` | string[] | no | Steps for this verification only (default: the key's flow). |
| `module_overrides` | object | no | Per-module settings, e.g. `{"form_data": {"values": {…}, "locked": […]}}`. |

Body size: at most 64 KB.

**`201 Created`**

| Field | Type | |
|---|---|---|
| `verification_id` | string (UUID) | The verification's id. |
| `url` | string (URL) | The link for the person. |
| `flow` | string[] | The steps it will go through. |
| `due_at` | string (time) | The link works until then. |
| `expires_at` | string (time) | The captured images are deleted then. |

Errors: `401 SDK_KEY_INVALID`, `402 CREDITS_EXHAUSTED`,
`403 SERVER_SIDE_ONLY`, `413 BODY_TOO_LARGE`, `422 FLOW_INVALID`,
`422 RELYING_PARTY_INACTIVE`, `502 BACKEND_UNREACHABLE`,
`503 SYSTEM_TEMPORARILY_UNAVAILABLE`, `500 GENERATE_FAILED`.

## Read a verification

`GET /api/v1/verifications/{verification_id}`

**`200 OK`**

| Field | Type | |
|---|---|---|
| `verification_id` | string | |
| `status` | string | See [statuses](https://docs.zetaid.com/guides/get-the-result/#what-the-status-means). |
| `terminal` | boolean | The checks have finished. |
| `reason_code` | string \| null | Why it ended this way (e.g. `DOCUMENT_EXPIRED`, `COMPLETION_TIMEOUT`). |
| `export` | object \| null | The result ([The result](https://docs.zetaid.com/reference/result/)); `null` before the checks ran and after personal-data retention. |
| `extra_data` | object \| null | What you sent at creation. |
| `created_at` | string (time) | |
| `updated_at` | string (time) | Last status change. |

Errors: `401 SDK_KEY_INVALID`, `403 SERVER_SIDE_ONLY`,
`404 VERIFICATION_NOT_FOUND` (unknown, or another organization's),
`502 BACKEND_UNREACHABLE`.

## Errors

Every error has the same shape:

```json
{ "error": { "code": "FLOW_INVALID", "message": "optional detail" } }
```

Branch on `code`; `message` is for logs. All codes: [Errors](https://docs.zetaid.com/reference/errors/).

---

# Webhooks

Source: https://docs.zetaid.com/reference/webhooks/

ZetaID sends `POST` requests with a JSON body to the webhook URL of the key
that created the verification. A key without a webhook URL gets none.

## Headers

| Header | |
|---|---|
| `Content-Type` | `application/json` |
| `X-Webhook-Event` | The event name, as in the body. |
| `X-Webhook-Delivery` | The delivery id (`whd_…`), the same on every retry of it. |
| `X-Webhook-Timestamp` | Unix time in seconds when this attempt was sent. |
| `X-Webhook-Signature` | `sha256=<hex>`: HMAC-SHA256 with your key's signing secret over `<X-Webhook-Timestamp>.<raw body>`. |

How to check it: [Get the result → Check the signature](https://docs.zetaid.com/guides/get-the-result/#check-the-signature).

## Delivery

- Answer with `2xx` within 20 seconds. Anything else is retried, up to 8
  attempts over about two hours, with growing gaps between them.
- A retry carries the same body and `X-Webhook-Delivery`, with a new
  timestamp and signature.
- Deliveries can arrive more than once and out of order. Use
  `X-Webhook-Delivery` to drop repeats, and the verification's `status` (not
  the arrival order) to decide.

## Events

### verification.completed

The checks decided.

| Field | Type | |
|---|---|---|
| `event` | string | `verification.completed` |
| `verification_id` | string | |
| `status` | string | `verified`, `rejected` or `needs_manual_review` |
| `reason_code` | string \| null | Why, when not plainly verified. |
| `export` | object | The result ([The result](https://docs.zetaid.com/reference/result/)). |
| `extra_data` | object \| null | What you sent at creation. |
| `completed_at` | string (time) | |

### verification.reviewed

Someone in your organization decided a `needs_manual_review` verification in
the operator console.

| Field | Type | |
|---|---|---|
| `event` | string | `verification.reviewed` |
| `verification_id` | string | |
| `status` | string | `verified` or `rejected` |
| `reason_code` | string \| null | The reviewer's reason. |
| `extra_data` | object \| null | |
| `reviewed_at` | string (time) | |

It carries no `export`: the result you received with
`verification.completed` stays valid; read it again with `GET` if you need it.

### verification.expired

The person didn't finish: the link's deadline passed (`COMPLETION_TIMEOUT`),
or they started and stopped for longer than the key allows (`ABANDONED`,
default 24 hours).

| Field | Type | |
|---|---|---|
| `event` | string | `verification.expired` |
| `verification_id` | string | |
| `status` | string | `expired` |
| `reason_code` | string | `COMPLETION_TIMEOUT` or `ABANDONED` |
| `extra_data` | object \| null | |
| `expired_at` | string (time) | |

---

# The result

Source: https://docs.zetaid.com/reference/result/

The `export` in `verification.completed` and in
`GET /api/v1/verifications/{id}` is what the checks read and decided. Which
blocks are filled depends on the flow and on the document.

```json
{
  "status": "ready",
  "created_at": "2026-11-01T10:19:40Z",
  "personal_info": {
    "first_name": "ERIKA",
    "last_name": "MUSTERMANN",
    "date_of_birth": "1983-08-12",
    "nationality": "D",
    "sex": "F"
  },
  "document_info": {
    "document_type": "national_id",
    "issuing_country": "D",
    "document_number": "T22000129",
    "expiry_date": "2031-07-31"
  },
  "contact_info": {},
  "additional_data": { "place_of_birth": "BERLIN" },
  "verification_checks": {
    "document_expiry": "passed",
    "mrz_quality": "passed",
    "face_match": "passed",
    "name_consistency": "passed"
  },
  "biometric_results": { "face_match_distance": 0.38 }
}
```

## Blocks

| Block | From | |
|---|---|---|
| `personal_info` | `document` (and `nfc`) | `first_name`, `last_name`, `date_of_birth` (YYYY-MM-DD), `nationality`, `sex` — as printed in the machine-readable zone (ICAO codes: `D` Germany, `ESP` Spain, …). |
| `document_info` | `document` | `document_type`, `issuing_country`, `document_number`, `expiry_date`; `personal_number` when the document carries a second number (e.g. the DNI/NIE on Spanish cards). |
| `contact_info` | `form_data`, `email`, `phone` | The values the person entered or confirmed. |
| `additional_data` | `document` | Further fields some documents carry (address, place of birth, …). |
| `verification_checks` | all | Each check by name with its outcome (below). |
| `biometric_results` | `liveness` | `face_match_distance` (lower = more alike) and similar measures. |
| `nfc_data` | `nfc` | The chip read and its authentication. |
| `aml` | `aml` | Sanctions screening: possible matches with the lists screened. |
| `attributes` | keys set up for attributes | E.g. `{"age_over_18": {"value": true, "source": "document"}}` instead of the identity. |

## Checks

`verification_checks` maps each check that ran to its outcome: `passed`,
`failed`, or `not_used` when another check decided instead. Checks you may
see: `document_expiry`, `mrz_quality`, `mandatory_fields`,
`name_consistency`, `sides_match`, `template_consistency`, `forgery`,
`face_match`, `nfc_chip`, `chip_face_match`, `chip_document_face_match`,
`aml_screening`, `wallet_claims`.

## Reason codes

`reason_code` (in webhooks and `GET`) says why a verification ended as it
did. Examples: `DOCUMENT_EXPIRED`, `BIOMETRIC_FACE_MATCH_FAILED`,
`NAME_MISMATCH`, `MISSING_MANDATORY_FIELDS`, `IMAGE_TOO_BLURRY`,
`POTENTIAL_FORGERY`, `SIDES_DO_NOT_MATCH`, `MRZ_QUALITY_LOW`,
`COMPLETION_TIMEOUT`, `ABANDONED`. New codes are added over time: show a
generic message for codes you don't know, and log them.

> **Less data, if you prefer**
  If you only need an answer like *over 18*, a key can be set up to receive
  only `attributes` and no identity — talk to us. The key's personal-data
  retention decides how long the `export` stays readable at all.

---

# Errors

Source: https://docs.zetaid.com/reference/errors/

```json
{ "error": { "code": "SDK_KEY_INVALID" } }
```

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| 401 | `SDK_KEY_INVALID` | No key, a wrong one, or a deactivated one. | Check the key in your secret store and in **API keys**. |
| 402 | `CREDITS_EXHAUSTED` | Prepaid balance below zero. | Top up under **Billing**. Running verifications continue. |
| 403 | `SERVER_SIDE_ONLY` | The request came from a web page (`Origin` header). | Call the API from your server. |
| 404 | `VERIFICATION_NOT_FOUND` | No such verification for your organization. | Check the id you stored. |
| 413 | `BODY_TOO_LARGE` | The request body is over 64 KB. | Keep `extra_data` small. |
| 422 | `FLOW_INVALID` | An unknown module in `flow`, or only automatic steps. | Use module names from [Configure a key](https://docs.zetaid.com/guides/configure-a-key/#flow-module-order). |
| 422 | `RELYING_PARTY_INACTIVE` | A `wallet` step without an active wallet registration. | Talk to us about wallet checks. |
| 500 | `GENERATE_FAILED` | The verification could not be created. | Retry once; contact us if it persists. |
| 502 | `BACKEND_UNREACHABLE` | The portal couldn't reach the verification service. | Retry after a short wait. |
| 503 | `SYSTEM_TEMPORARILY_UNAVAILABLE` | Image checks can't start right now. | Retry after a short wait; flows without image steps still work. |

Retry only `5xx` answers, with a growing wait (for example 2, 5, 15 seconds).
Never retry `4xx` unchanged.

---

# Agent skill

Source: https://docs.zetaid.com/agents/agent-skill/

If you build with a coding agent (Claude Code, Cursor, Copilot, …), give it
our **integration skill**: a short instruction file with the integration's
model, its hard rules (secrets on the server, signature checks, the server
decides) and what to build. With it, the agent builds the same safe
integration this documentation describes.

**Download:** [SKILL.md](https://docs.zetaid.com/agent-skill/zetaid-integration/SKILL.md)

## Install

  **Claude Code**
In your project:

```sh
mkdir -p .claude/skills/zetaid-integration
curl -fsSL https://docs.zetaid.com/agent-skill/zetaid-integration/SKILL.md \
  -o .claude/skills/zetaid-integration/SKILL.md
```

Then ask: *"Add ZetaID identity verification to the checkout."* Claude Code
picks the skill up by itself.
  
  **Other agents**
Add the file to the agent's instructions or rules (for example
`.cursor/rules/zetaid.md`, `AGENTS.md`, or paste it into the chat), or point
the agent at `https://docs.zetaid.com/agent-skill/zetaid-integration/SKILL.md`.
  

## Machine-readable docs

| File | |
|---|---|
| [/llms.txt](https://docs.zetaid.com/llms.txt) | An index of these docs for language models. |
| [/llms-full.txt](https://docs.zetaid.com/llms-full.txt) | All pages as one text file. |
| [/openapi.yaml](https://docs.zetaid.com/openapi.yaml) | The API and webhooks as OpenAPI 3.1. |

> **Review what the agent builds**
  Check in particular that the API key and webhook secret are read from your
  secret store, that the webhook route verifies signatures on the raw body,
  and that your checkout trusts only what your server stored.