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_xxxxxxxxxxxxxxxxxxxxxThe flow
- 1. Open a verification (
POST /verifications). It costs nothing and does not expire. - 2. Generate the link (
POST /verifications/{id}/attempts) and send it to the person however you like. - 3. The person opens the link: consent, document, liveness. Nothing to install.
- 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. You receive
verification.approved,.declinedor.retry_required.
Endpoints
/api/v1/verificationsOpens 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": "…" }/api/v1/verifications/{id}/attemptsGenerates 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 }/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.