Create a session

Build withCopy prompt

POST /api/kyc/sessions

Mints a hosted verification link for one applicant from one of your published workflows, entirely server to server. You get back a URL that is theirs alone: send it by email, SMS, WhatsApp, or render it as a QR, and the applicant completes the flow on our hosted page with no SDK integration on your side.

The session is the link. It carries one verification, it is traceable to your own reference for the applicant, and once it is submitted it is spent. Forwarding it to a second person does not work. This is the API twin of the dashboard's "Create session" action; the two accept the same request and mint the same thing.

Authentication: Authorization: Bearer sk_… (secret key required). The response contains a live verification credential and the request may carry applicant details, so this endpoint is backend-only. A publishable key receives 403 secret_key_required. Content type: application/json. Production note: sk_live_ keys require an approved business.

Looking for one URL many people can open, each visit starting its own verification? That is a workflow's hosted link. This endpoint is the opposite shape: you know the applicant, and you want a link that is theirs.

Request body

Build withCopy prompt

A biometric-authentication workflow must name its subject at mint time: pass externalUserId for a user with an active biometric enrolment, or faceReferenceMediaId with a reference photo. Neither present is refused with 422 user_reference_required; a reference without an enrolment with 422 not_enrolled. A biometric-enrolment workflow always requires externalUserId (the template binds a face to a named record). This is checked when the session is created, so a link that could only fail at submit is never minted.

Request

Build withCopy prompt

curl "https://trust.myaza.app/api/kyc/sessions" \
  -H "Authorization: Bearer $MYAZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf_AbC123dEf456",
    "externalUserId": "user_42",
    "metadata": { "loanId": "loan_20191" },
    "userData": { "firstName": "John", "lastName": "Doe" },
    "email": "john@example.com"
  }'

Response 201 Created

Build withCopy prompt

{
  "session": {
    "sessionId": "cmt1gfjce05g547grqbmjsiqf",
    "url": "https://trust.myaza.co/verify/pXk3...",
    "shortCode": "7K9F-2QHM",
    "expiresAt": "2026-08-21T12:00:00.000Z",
    "kind": "individual",
    "externalUserId": "user_42",
    "metadata": { "loanId": "loan_20191" },
    "workflow": { "id": "wf_AbC123dEf456", "name": "Identity verification", "version": 3 }
  },
  "delivery": { "sent": true }
}

The config the applicant walks is the workflow's published snapshot, frozen at mint time. Editing or re-publishing the workflow never changes a link that is already in someone's inbox.

Tracking the session

Build withCopy prompt

The sessionId doubles as the verification's id once the applicant submits, so the reference you hold from the start resolves from the start:

• GET /status/:id reports the attempt live: in_progress with the current step and captured slots, then the full verification lifecycle after submission, and abandoned or expired if the applicant never finishes.
• Session webhooks (session.started, session.resumed, session.abandoned, session.expired) push the same lifecycle to your backend, and the verification events follow once they submit.
• Opening the url in a WebView or an iframe? The page tells its host what the applicant is doing, step by step, with nothing to install: see Hosted link events.

Errors

Build withCopy prompt