International Verification

International verification lets an entity prove who they are, or where they live, by capturing a document with their camera. Identity flows also include a selfie liveness check. DAL verifies the document and updates the entity’s record. You drive the whole flow from your own backend and your own UI through the CRM API. Two verification types are supported. Each is an independent flow with its own token, its own records, and its own blocking rules.

Type	What the entity captures	What DAL writes on success
`Identity`	A government ID (passport, national ID, residency permit, driving licence) plus a selfie liveness check	A verified identity on the entity, the entity’s name, date of birth, gender and nationality, the cropped document images and the selfie, and the KYC nationality and country-of-residence answers
`Address`	A proof-of-address document (utility bill, bank statement)	An `International` address on the entity, either `Verified` or `Submitted` for admin review, with the document attached

How the Pieces Fit

Your backend asks DAL for a session token. Your web page or mobile app resumes that session in the SDK. When capture ends, DAL notifies you by webhook. Two things in this diagram matter most:

The session already exists when you get the token. Your UI only ever resumes the session it was given.
Completion is asynchronous. The SDK’s onJourneyFinished means the entity has finished capturing. DAL’s decision arrives seconds to a couple of minutes later, by webhook.

Step by Step

Generate a session token

Ask DAL to start a verification session for the entity and issue a short-lived token bound to it. type is identity or address (case-insensitive). If the entity already has a session of this type that has not finished, DAL reuses it instead of starting another, so calling this again after a page reload simply lets the entity pick up where they left off.Endpoint: Generate international verification tokenThe token is valid for one hour. Request a new one on each visit rather than caching it; the same session is reused. DAL refuses the call with 403 when the entity is not eligible: it is blocked for this type, or the type is not enabled on your tenant. An entity can verify more than one identity document. Running an identity flow again with a document that already exists on the entity re-verifies it and refreshes its details, expiry, and images. You do not need to check eligibility yourself.

Resume the session in your UI

Hand clientToken, flowId and trialId to your front end. Load the web SDK, mount it into an element on your page, and resume the session. See IDwise’s Web SDK usage and Resuming a journey pages for the full SDK reference.

<script src="https://releases.idwise.com/websdk/latest/idwise.min.js"></script>
<div id="verification-mount"></div>

// values from your backend (step 1)
const { clientToken, flowId, trialId } = tokenResponse;

const session = await window.IDWise.initialize({
  clientKey: clientToken,
  locale: "en",              // or "ar"
  theme: "system_default",   // "light" | "dark" | "system_default"
});

session.resumeJourney({
  flowId,
  journeyId: trialId,
  mount: "#verification-mount",
  eventHandlers: {
    onJourneyFinished: () => showProcessingState(),   // wait for your webhook
    onJourneyCancelled: () => showCancelledState(),
    onError: ({ code, message }) => showErrorState(message),
  },
});

// when your page unmounts
session.cleanup();

Always call resumeJourney, never startJourney. The token is bound to the session DAL started, so startJourney fails, and a session started from the browser would not be linked to the entity.

Keep the entity’s profile up to date before requesting a token. DAL cross-checks it against the captured document.

Receive the outcome

After the entity finishes, DAL processes the result, updates the entity, and sends you an IntlVerificationUpdate webhook. Treat this event as the single source of truth for the session’s outcome.Payload: International verification event

{
  "eventType": "IntlVerificationUpdate",
  "timestamp": "2026-09-14T12:04:31.512Z",
  "data": {
    "entity": {
      "id": "b50c7893-cd88-42bd-9fdd-b94f493315f9",
      "crmId": "CUST-000123"
    },
    "verificationId": "7a1f2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "trialId": "6aa8e8059c85cb8faa1b20f1",
    "type": "Identity",
    "status": "Completed",
    "isFailed": false,
    "reasons": [],
    "verificationBlocked": null
  }
}

Field	Meaning
`verificationId`	ID of the verification record. Matches `id` in the list records endpoint.
`trialId`	The session this outcome belongs to. Matches `trialId` from the token response.
`type`	`Identity` or `Address`
`status`	`Completed` or `Failed`
`isFailed`	`false` when DAL accepted the document and wrote the results to the entity. `true` when the attempt was rejected.
`reasons`	On failure, the names of the checks that failed. Empty on success. See failure reasons for the catalogue.
`verificationBlocked`	`Identity`, `Address`, or `null`. When it equals `type`, the entity cannot start new sessions until a compliance officer resets it.

On isFailed: false, refresh your copy of the entity with view client or view prospect to read what was written. For identity flows the item in identities for that document (new, or updated when the number already existed) has verifiedAt set, source Automatic, and type reflecting the document (Passport, NationalIdentity, ResidencyPermit, DrivingLicense, or Other). For address flows, list the entity’s addresses with list entity addresses.On isFailed: true, check verificationBlocked in the payload. If it equals type, the entity has hit a blocking rule and cannot retry until a compliance officer resets it from the DAL portal. Otherwise the entity may simply generate a new token and try again.

Identity flows and KYC. If the entity has a KYC in progress, a successful identity verification also fills its nationality and country-of-residence answers and re-evaluates the KYC. A KycStatusUpdate webhook follows only when the KYC status changes as a result: KycPending when the entity can now proceed to forms, ConsentPolicyPending when the consent policy is still unsigned, or KycBlocked when the verified nationality or issuing country is on your block list. A KYC already in KycPending with a clean nationality stays there and sends no KYC event. A blocked country is not reported as a verification failure; isFailed is false and the block appears only on the KYC.

Address flows and review. When the proof-of-address document passes capture but not every validation rule, DAL still accepts it and creates the address with status Submitted for an admin to review, rather than Verified. isFailed is false in both cases. There is no webhook for the admin’s decision; poll the address list if you need to know when it becomes Verified.

List verification records

Every attempt is stored as a record with its outcome. Use this to build an attempt history, show failure reasons to your staff, or reconcile after a missed webhook.Endpoint: List international verification recordsstatus is Pending (session started, no decision yet), Completed, or Failed. A Failed record with a non-null resetAt has been cleared by a reset and no longer counts toward blocking. The optional filters[status] query narrows the list to one status. The list is not paginated; all records of the requested type are returned.

Resetting a blocked entity is not part of the API. Your compliance officer lifts the block from the DAL portal, which stamps resetAt on the active Failed records and sets verificationBlocked back to null.

Blocking Rules

A block stops the entity generating new tokens for that flow type until a compliance officer resets it. The rules differ by type.

Type	Blocks when
`Identity`	The third active `Failed` record is written (three failures since the last reset), or any attempt fails a device-intelligence signal (VPN, proxy, TOR, emulator, bot, app tampering, and similar)
`Address`	An attempt fails a device-intelligence signal. Document failures alone never block an address flow.

DAL’s own checks count toward the identity limit like any other failure: Invalid Identity Number, Duplicate Identity (the document number already belongs to another entity in your tenant), No verifiable document, and Blocked. While an entity is blocked for identity, any identity session that finishes is recorded as Failed with reason Blocked. Address sessions are unaffected. A new identity session can only start after the reset.

Failure Reasons

reasons in the webhook, and failedReasons in the record list, carry the names of the checks that did not pass. They fall into four groups. Document checks run on the captured images and extracted fields, for example Physical Document Check (Front), Document Expired, Photo Substitution Check (Front), Image Injection Check (Front), Suspicious Document (Front), Capture Quality (Front), Field Presence: Birth Date (Front), Field Format: Document Number (Front), Cross Check: Full Name, Valid Logical Dates Check, ID Document Sides Check. Journey rules are flow-level decisions: Recognised Document, Authentic Document, Expired Document, Approved Nationality, Document Quality, Unique Applicant, Same Person, Selfie Liveness, Device Intelligence Checks. Device signals trigger a block: App Tampering, Bot, Browser Incognito, Emulator, High Device Usage, IP Restriction, Proxy, TOR, VPN. DAL checks run after the document is accepted: Invalid Identity Number, Duplicate Identity, No verifiable document, Blocked, Address extraction from document failed. The record list returns each reason as an { en, ar } pair; the webhook returns the English name only.

Go-Live Checklist

A test token request succeeds for each verification type you use.
Webhook endpoint Active and handling IntlVerificationUpdate and KycStatusUpdate.
SDK code calls resumeJourney with the trialId and flowId from the token response.

Getting Started

Integration

Transaction Monitoring

Breaking Changes

How the Pieces Fit

Step by Step

Blocking Rules

Failure Reasons

Go-Live Checklist

​How the Pieces Fit

​Step by Step

​Blocking Rules

​Failure Reasons

​Go-Live Checklist

How the Pieces Fit

Step by Step

Blocking Rules

Failure Reasons

Go-Live Checklist