Verify again
POST /api/kyc/verifications/:id/rerunMints a fresh hosted session from a finished verification: the same workflow, the same person reference, a new attempt. Use it when a document has expired, a check failed on something fixable, or your own policy asks for periodic re-verification. This is the API twin of the dashboard's "Verify again" button; the two run the same core and mint the same thing.
The original verification is never touched. It records what was found at a moment, and the new attempt is its own verification, stamped with a reference back to the one it retries.
Authentication: Authorization: Bearer sk_… (secret key required). The response contains a live verification credential. A publishable key receives 403 secret_key_required.
Content type: application/json.
Production note: sk_live_ keys require an approved business.
Redo only what failed
By default the applicant walks the whole flow again. Pass steps to narrow the new attempt to specific sections instead: a selfie that did not match does not require the applicant to re-photograph a perfectly good document.
{ "steps": ["liveness"], "message": "Your selfie was too dark to match. Please retake it in good light." }The applicant's session then walks only the ticked steps, with your message shown when they open the link. Valid step names:
| Step | What the applicant redoes |
|---|---|
id-type | ID type selection |
id-input | Typing their ID number |
document-capture | Document photos |
liveness | Selfie and liveness |
proof-of-address | Proof of address |
nfc | Chip scan |
email-verification | Email confirmation |
phone-verification | Phone confirmation |
business-details | Business details (KYB) |
business-key-people | Directors and owners (KYB) |
business-documents | Business documents (KYB) |
questionnaire | Questionnaire |
An unknown step name is refused with 400 invalid_steps rather than ignored. A silently dropped typo would turn a targeted redo into a full re-run, which is the one failure you could not see happening.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
steps | string[] | no | Sections to redo, from the table above. Absent or empty means the whole flow. |
message | string | no | Shown to the applicant on a narrowed flow, up to 500 characters. Write it for them, not for your logs. |
Request
curl "https://trust.myaza.app/api/kyc/verifications/ver_abc123/rerun" \
-H "Authorization: Bearer $MYAZA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "steps": ["liveness"] }'Response 201 Created
{
"session": {
"sessionId": "cmt1gfjce05g547grqbmjsiqf",
"url": "https://trust.myaza.co/verify/pXk3...",
"shortCode": "7K9F-2QHM",
"expiresAt": "2026-08-22T12:00:00.000Z",
"kind": "individual",
"workflow": { "id": "wf_AbC123dEf456", "name": "Identity verification", "version": 3 }
},
"retryOf": "ver_abc123",
"steps": ["liveness"],
"full": false
}| Field | Description |
|---|---|
session | The applicant's fresh session, the same shape creating a session returns. session.url is a credential: whoever opens it verifies as this applicant. |
retryOf | The verification this attempt retries. The new verification carries the same link, so the two stay connected in your records and ours. |
steps | The plan the session was minted with, in flow order. |
full | true when the whole flow will run, which is what absent or empty steps produces. |
The new session runs the workflow's current published snapshot, so a flow you have improved since the first attempt is the flow the applicant meets. Track the attempt exactly as any session: the sessionId doubles as the new verification's id from the start.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_steps | A step name is not in the table above. The message lists the valid names. |
| 404 | verification_not_found | No verification with that id in your organisation and environment. |
| 409 | verification_in_progress | The verification has not finished. A pending check may still come back clean, and a second attempt would charge twice. |
| 422 | no_workflow | The verification did not run a workflow, so there is no published flow to repeat. Start the person again from your own integration. |
| 429 | rate_limited | Too many sessions started this hour. Try again shortly. |
Re-running is allowed from any terminal status, including a passed verification. Re-verifying someone whose document is about to expire is the same operation as retrying a failure.