On this page
Verification events describe one individual verification from processing to a terminal result. All five names use the same data schema, so a handler can upsert one record by verificationId and branch on type and status.
Lifecycle
| Event | When it fires | Recommended handling |
|---|---|---|
verification.started | The verification enters processing. | Record the IDs and show a processing state. Do not treat it as a completed check. |
verification.completed | The verification completes successfully. | Persist the result and continue the approved customer flow. |
verification.failed | The check completes with a failed identity, data or biometric result. | Show the public reason; route according to your policy. |
verification.not_found | The submitted identity cannot be found. | Ask the customer to verify the identifier or use another supported method. |
verification.error | A verification service error stops processing. | Keep the customer retryable and use reasonCode for support diagnostics. |
Complete successful payload
json
{
"version": "2026-08-11",
"id": "evt_4d6628b920d940d48ae7ac2e",
"type": "verification.completed",
"createdAt": "2026-08-15T12:14:37.150Z",
"deliveryId": "del_01j9verification01",
"data": {
"verificationId": "ver_sample0000000000",
"requestId": "req_sample_verified",
"externalId": "your_user_123",
"workflowId": "wf_sample0000000000",
"workflowVersion": 3,
"status": "VERIFIED",
"reason": null,
"reasonCode": null,
"verificationMethod": "sandbox",
"assuranceLevel": null,
"idType": "bvn",
"country": "NG",
"subjectType": "individual",
"idNumber": "00000000001",
"business": null,
"questionnaire": null,
"proofOfAddress": null,
"nfc": null,
"emailVerification": null,
"phoneVerification": null,
"deviceIntel": null,
"userData": {
"firstName": "Amina",
"lastName": "Okafor",
"middleName": null,
"dateOfBirth": "1992-04-18",
"gender": "female"
},
"facialMatch": true,
"facialConfidence": 92,
"dataMatch": true,
"media": {
"selfie": "/api/verifications/ver_sample0000000000/media/selfie",
"livenessVideo": "/api/verifications/ver_sample0000000000/media/liveness-video"
},
"environment": "SANDBOX",
"createdAt": "2026-08-15T12:14:31.004Z"
}
}Media values are absolute authenticated URLs in a live delivery. Fetch them with your API key. The illustrative relative paths above show the resource shape without exposing a deployment host.
Event-specific examples
The repeated identity result fields follow the complete schema above. These fixtures show the fields that distinguish the other four event types.
json
[
{
"version": "2026-08-11",
"id": "evt_started_01",
"type": "verification.started",
"createdAt": "2026-08-15T12:14:31.004Z",
"deliveryId": "del_started_01",
"data": {
"verificationId": "ver_sample0000000000",
"requestId": "req_sample_pending",
"externalId": "your_user_123",
"workflowId": "wf_sample0000000000",
"workflowVersion": 3,
"status": "PENDING",
"reason": null,
"reasonCode": null,
"verificationMethod": "sandbox",
"assuranceLevel": null,
"idType": "bvn",
"country": "NG",
"subjectType": "individual",
"idNumber": "00000000001",
"environment": "SANDBOX",
"createdAt": "2026-08-15T12:14:31.004Z"
}
},
{
"version": "2026-08-11",
"id": "evt_failed_01",
"type": "verification.failed",
"createdAt": "2026-08-15T12:15:03.421Z",
"deliveryId": "del_failed_01",
"data": {
"verificationId": "ver_failed_01",
"requestId": "req_sample_failed",
"externalId": "your_user_124",
"workflowId": "wf_sample0000000000",
"workflowVersion": 3,
"status": "FAILED",
"reason": "The user's selfie does not match the photo on file with the government database (match confidence 38%, minimum 70% required).",
"reasonCode": "selfie_mismatch",
"verificationMethod": "sandbox",
"assuranceLevel": null,
"idType": "bvn",
"country": "NG",
"subjectType": "individual",
"idNumber": "00000000002",
"facialMatch": false,
"facialConfidence": 38,
"dataMatch": false,
"environment": "SANDBOX",
"createdAt": "2026-08-15T12:14:58.050Z"
}
},
{
"version": "2026-08-11",
"id": "evt_not_found_01",
"type": "verification.not_found",
"createdAt": "2026-08-15T12:16:18.120Z",
"deliveryId": "del_not_found_01",
"data": {
"verificationId": "ver_not_found_01",
"requestId": "req_sample_not_found",
"externalId": "your_user_125",
"workflowId": null,
"workflowVersion": null,
"status": "NOT_FOUND",
"reason": "The BVN number was not found in the government database.",
"reasonCode": "identity_not_found",
"verificationMethod": "gov_db",
"assuranceLevel": null,
"idType": "bvn",
"country": "NG",
"subjectType": "individual",
"idNumber": "00000000003",
"environment": "SANDBOX",
"createdAt": "2026-08-15T12:16:11.004Z"
}
},
{
"version": "2026-08-11",
"id": "evt_error_01",
"type": "verification.error",
"createdAt": "2026-08-15T12:17:40.902Z",
"deliveryId": "del_error_01",
"data": {
"verificationId": "ver_error_01",
"requestId": "req_sample_error",
"externalId": "your_user_126",
"workflowId": "wf_sample0000000000",
"workflowVersion": 3,
"status": "ERROR",
"reason": "A temporary system error prevented this verification from being processed. No charge was applied.",
"reasonCode": "system_error",
"verificationMethod": "gov_db",
"assuranceLevel": null,
"idType": "bvn",
"country": "NG",
"subjectType": "individual",
"idNumber": "00000000004",
"environment": "SANDBOX",
"createdAt": "2026-08-15T12:17:35.418Z"
}
}
]Field reference
| Field | Type | Nullable | Values and meaning |
|---|---|---|---|
verificationId, requestId | string | No | Stable verification and request identifiers. |
externalId | string | Yes | Your customer reference supplied with the request. |
workflowId | string | Yes | Published workflow that configured the run. |
workflowVersion | integer | Yes | Exact published version that ran. Pair it with workflowId. |
status | string | No | PENDING, VERIFIED, FAILED, NOT_FOUND or ERROR. |
reason, reasonCode | string | Yes | Populated for failure outcomes. Codes are stable for routing; copy is suitable for display. |
verificationMethod | string | Yes | gov_db, document_ocr or sandbox. Internal source names are deliberately hidden. |
assuranceLevel | string | Yes | For a verified result: chip, gov_db or document. |
idType, country | string | No | Submitted ID type and ISO 3166-1 alpha-2 country. |
subjectType | string | No | individual or business. Business fields are documented separately. |
idNumber | string | Yes | Submitted identifier where the method uses one. |
business | object | Yes | Customer-safe registry result for business checks. |
questionnaire, proofOfAddress, nfc | object | Yes | Workflow sub-results when those steps ran. |
emailVerification, phoneVerification | object | Yes | Contact possession sub-results when enabled. |
deviceIntel | object | Yes | Device, IP and soft-signal result when enabled. |
userData | object | Yes | Individual identity fields. Null for a business subject. |
facialMatch, dataMatch | boolean | Yes | Biometric and identity-data match results. |
facialConfidence | number | Yes | Facial match confidence from the completed check. |
media | object | Yes | Authenticated URLs for captured media. |
environment | string | No | Environment that produced the event. |
createdAt | ISO 8601 string | No | Verification record creation time. This differs from the envelope event time. |
Related APIs and events
Read the verification resource when you need the latest state or full nested sub-results. workflow.run.completed, credits.deducted, entity.created and identity.resolved can refer to the same customer journey, but they are separate logical events and can arrive in a different order.
See Authentication for signature verification and Webhook Testing for signed simulator delivery.