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,
"deviceRules": 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. |
deviceRules | object | Yes | What the workflow's Device Intelligence settings decided: result (the deciding finding or clear), action (approve, review or decline), every finding in cases, ipCountry and countryAllowed (the geofence verdict, null when it does not apply). Null when the settings were not applied. |
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.