> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first. # Verification > Handle individual verification lifecycle events and their complete public result contract. 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": "00000000004", "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": "00000000002", "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": "00000000016", "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](/integrate/webhooks/signatures) for signature verification and [Webhook Testing](/integrate/webhooks/testing) for signed simulator delivery.