API documentation

Three calls to integrate verification, plus webhooks to find out how it went.

Authentication

Every request carries the key in the Authorization header. You create keys in the dashboard, under API keys, and you see each one in full only once.

Authorization: Bearer kyc_live_xxxxxxxxxxxxxxxxxxxxx
Test and live are separated by the key
A kyc_test_… key cannot create live data. It is not a parameter you can forget: the key itself decides.
What the sandbox costs
The first 20 test verifications each month are free. Beyond that, they are charged to your balance just like live ones, module by module: a test verification runs the same checks as a real one, and it costs us the same.

The flow

  1. 1. Open a verification (POST /verifications). It costs nothing and does not expire.
  2. 2. Generate the link (POST /verifications/{id}/attempts) and send it to the person however you like.
  3. 3. The person opens the link: consent, document, liveness. Nothing to install.
  4. 4. You receive verification.submitted: they have finished. If you switched on automatic approval and the case is green on every check, the approval follows straight away; otherwise a person decides — your team from the dashboard, or one of our operators on the Institutional plan.
  5. 5. You receive verification.approved, .declined or .retry_required.
There is always a person in the loop
The automated checks measure; on their own they do not approve. Every case that is not approved automatically is decided by a person — your team, from the dashboard, on the Standard plan; one of our operators on the Institutional plan — which is why the outcome does not come back in the same call. The only exception is yours to make: automatic approval, off until you switch it on, approves without review only cases green on every check — with the chip, or from the photograph too if you accepted that extension — and never refuses.

Endpoints

POST/api/v1/verifications

Opens a verification. It generates no link and costs nothing.

REQUEST

{ "external_ref": "cliente-4821", "declared_name": "Mario Rossi", "return_url": "https://app.esempio.it/firma/abc" }

RESPONSE

{ "id": "…", "status": "created", "livemode": true, "created_at": "…" }
POST/api/v1/verifications/{id}/attempts

Generates the link. Single-use, with an expiry. A new attempt invalidates the previous one.

REQUEST

{ "instruction": "Fotografa il documento disteso, senza riflessi." }

RESPONSE

{ "id": "…", "url": "https://…/v/<token>", "expires_at": "…", "livemode": true }
GET/api/v1/verifications/{id}

Status, outcome and who decides the case, with the data read from the document when there is any.

RESPONSE

{ "id": "…", "status": "approved", "record": { "surname": "…", "verifiedFields": […] } }

Webhooks

You configure the endpoint in Settings. In live mode it must be https.

The body

It never contains personal data. Only identifiers: you read the data yourself with GET /verifications/{id}, authenticated.

{
  "id": "285a4274-a751-4a24-9479-12100bf9d313",
  "type": "verification.approved",
  "created": 1787037080,
  "livemode": true,
  "data": {
    "verification_id": "01a013b5-dc12-7ab2-a8c5-f00f0bab35bc",
    "status": "approved",
    "external_ref": "cliente-4821"
  }
}

Verifying the signature

The X-KYCJET-Signature header is t=<timestamp>,v1=<hmac>. The HMAC is SHA-256 over "<timestamp>.<raw body>" with your signing secret. Compare in constant time and reject timestamps that are too old.

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifica(rawBody, header, secret) {
  const [t, v1] = header.split(',').map(p => p.split('=')[1])
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const atteso = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  return timingSafeEqual(Buffer.from(atteso), Buffer.from(v1))
}

Delivery and retries

Respond 2xx as soon as you have accepted the event. Any other response, or silence for more than 10 seconds, triggers a new attempt: exponential backoff from 30 seconds up to 6 hours, 12 attempts over about fifteen hours, after which the delivery is abandoned.

Delivery is at least once: the same event may reach you twice. Use id as the idempotency key — it stays identical even when we requeue a delivery by hand.

Errors

Every error has the same shape: { "code": …, "message": …, "details"?: … }. Switch on code, never on the message. The message comes in Italian, English or French according to Accept-Language; the code does not change.

401 UNAUTHORIZED
Key missing, wrong or revoked. The three responses are identical on purpose.
402 INSUFFICIENT_CREDITS
Insufficient balance (the code kept its old name for compatibility): if your balance does not cover the most a verification can cost, the POST that generates the link does not generate it. It happens before anyone is involved, not after.
404 VERIFICATION_NOT_FOUND
The verification does not exist, or does not belong to your organisation. Here too, the same response.
409 VERIFICATION_NOT_RETRYABLE
You asked for a new attempt on a verification that has already been decided. This code IS the retry policy.
422 DOCUMENT_REJECTED
The photo is unusable. Nothing charged, the link stays valid: the person retakes the photo.
503 CHECKS_UNAVAILABLE
Our checks are not responding. Our fault: the photos are fine, the link stays valid, nothing charged. The person tries again in a few minutes.