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.

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.
`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).

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:

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

The answer

201 Created:

{
  "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

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();

import os, requests

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"]

$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.