Integration Flow

Overview

Two-Phase Model

Phase 1 is interactive. The customer fills in personal details, uploads identity documents, and completes biometric capture in the VerifiMe portal. Your application controls when to start (Step 1) and is notified when the customer finishes (Step 4).

Phase 2 is asynchronous. VerifiMe validates documents against government databases, runs biometric checks, screens PEP/sanctions lists, and calculates a risk level. Your webhook endpoint receives the results when processing completes (Step 6).

Common misconception: onSuccess() and tracking status "Completed" do not mean the verification is complete. The tracking reference only tracks customer onboarding activity (Phase 1). It has no visibility into backend processing (Phase 2). The only signal that verification and risk assessment are complete is the RISK_ASSESSMENT_UPDATED webhook.

---

Step 1: Initiate Verification

Your application calls POST /v1/user/invite to create a tracking reference for the customer's verification session.

• When: You decide, typically after the customer completes your application form
• Action: Call POST /v1/user/invite
• Returns: trackingReference (UUID) for widget initialisation

---

Step 2: Widget Integration

Embed the VerifiMe widget on your page. It displays a QR code and verification button, and polls status automatically.

• When: Display widget on your page
• Action: Initialise widget with trackingReference
• Widget: Automatically polls the tracking status endpoint

---

Step 3: Customer Data Entry

The customer completes verification in the VerifiMe portal. This is handled entirely by VerifiMe - your application waits for the callback.

Return Path URL: VerifiMe can automatically redirect the customer back to your application after they complete data entry. This is configured per organisation code by your VerifiMe account manager.

---

Step 4: Widget Callback

The widget detects the customer has completed data entry and fires onSuccess(). The customer has returned to your application.

• Trigger: onSuccess() callback fires
• Meaning: Customer finished data entry (Phase 1 complete)
• Does NOT mean: Identity verified or risk assessment complete

The gap between phases: The customer is back in your application, but VerifiMe is still processing in the background. onSuccess() fires at the end of Phase 1 (data entry); the webhook arrives 1-3 minutes later at the end of Phase 2 (backend processing). Your application must handle this gap gracefully.

---

Step 5: Backend Processing

VerifiMe processes identity documents, biometrics, and risk assessment asynchronously. This takes 1-3 minutes.

---

Step 6: Webhook Delivery

VerifiMe sends the risk assessment results to your webhook endpoint.

• When: 1-3 minutes after the customer completes data entry
• Payload: Risk level, customer name, assessment status, your referenceData
• Required: Return HTTP 200 within 10 seconds

For full webhook details, see Webhook Setup and Event: RISK_ASSESSMENT_UPDATED.