WIDTH Identity Developer Documentation

WIDTH Identity provides a complete identity verification and compliance platform supporting KYC, KYB, transaction screening, and continuous monitoring workflows — accessible via REST APIs and drop-in SDKs for web, iOS, Android, and Flutter.

Capabilities

The platform supports KYC, KYB, transaction screening and continuous monitoring through the REST API. The Web and Mobile SDKs provide a managed verification experience for KYC and KYB.

Integration paths

Three primary integration methods. Use OpenAPI for full backend control, or the SDKs for a managed verification UX.

Environments

Two environments: staging for development and production for live traffic. Use the matching gateway, storage service and console below.

Credentials

Choose credentials for your integration path and environment. Mobile SDK credentials and Web SDK session tokens are configured differently.

How to obtain

1. Log in to the One Platform Console → API & Integration for your environment:
   • Staging API credentials
   • Production API credentials
2. Click Generate for the credential type required by your integration.
3. Copy and store credentials securely. The apiSecret is shown only once.

For the Web SDK, your backend signs the sdk.credentials request and returns the session token and selected domainId to the browser. Issue a new token for every verification; do not cache or reuse it. See the Web SDK session-token reference.

Getting started

Prepare your console configuration, run a first verification and confirm the final decision before connecting your downstream process.

Console prerequisites

1. Select your environment. Use the staging console for development and the production console for live traffic.
2. Confirm your Domain (Business Unit). A Domain separates the workflows, members and data for a business line or region. New tenants include a DEFAULT Domain. Manage additional Domains under Admin Console → Domains / Business Units.
3. Generate the appropriate credentials. Follow Credentials for OpenAPI, Mobile SDK or Web SDK access.
4. Configure and publish a workflow. In the console, publish the workflow for your event type and source channel. The API event values for individual and business verification are KYC_EVENT and KYB_EVENT; the console displays these as KYC and KYB.

Your first verification

1. Choose an integration path. Use the Web or Mobile SDK for a managed verification UI, or OpenAPI for your own customer-data collection flow.
2. Match the environment and credentials. Use the correct base URLs. SDK builds connect to a specific environment; check the selected package or build against your credentials before testing.
3. Start the verification. Initialise and launch the Web, Android, iOS or Flutter SDK. For OpenAPI, register the applicant, start the workflow and submit the required node data using the KYC or KYB guide.
4. Retrieve the result. Retain the executionId and poll workflow.execution.status, or configure a workflow webhook. See the status and case-decision reference and webhook integration guide.
5. Check the final decision and usage. Review the case in the Admin Console and check Billing. A submitted verification or a workflow waiting for manual review is not a final approval.

Workflows and the decision model

A workflow connects data collection, screening and rule checks to a decision. With automatic routing, WIDTH selects a published workflow using eventType and the source channel. KYC and KYB have one active workflow per source; transaction screening can have multiple workflows for the same event type. The Workflow Lifecycle API also documents an optional workflowId for version 2.0.0.

After user-input steps are complete, automatic checks and the decision step run. Some cases need manual review before a final decision is available. Use a Webhook Action node for a step's output, or a Decision Webhook for the final approve or reject decision and its action, code, reason and tags.

Set failure handling at the workflow level:

• Strict (default): any node failure fails the workflow.
• Lenient: only a failure on a critical node fails the workflow.
• Fully tolerant: the workflow continues regardless of node failures.

Usage and quota

Open Admin Console → Billing to review your current plan and usage statistics for the billing cycle: API Calls, Cases Processed, Workflows and Team Members.

• Screening operations consume quota in staging as well as production.
• If the gateway returns 999501 REQUEST_API_EXCEED_LIMIT, contact support to increase your limit. Check the gateway error reference before retrying.

Quick start — signing a request

Every OpenAPI request is signed with HMAC-SHA256 over the request body. The signature is appended as the sign query parameter.

sign = HmacSHA256(apiSecret, requestBody)

Both the key and body use UTF-8 encoding. The result is a 64-character lowercase hex string.

import hmac, hashlib

sign = hmac.new(
    api_secret.encode('utf-8'),
    request_body.encode('utf-8'),
    hashlib.sha256
).hexdigest()

const crypto = require('crypto');

const sign = crypto
  .createHmac('sha256', apiSecret)
  .update(requestBody, 'utf8')
  .digest('hex');

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes("UTF-8"), "HmacSHA256"));
byte[] hash = mac.doFinal(requestBody.getBytes("UTF-8"));
String sign = HexFormat.of().formatHex(hash);

See the authentication reference for the full request envelope, including headers, query parameters, and a worked example.

Additional integration guides

These topics are available in the developer reference guide:

• Verification Link — generate a hosted KYC or KYB verification link with sdk.launch.link.generate.
• Name Screening — screen a person or company using MANUAL_CASE_EVENT.
• Quick Scan API — one-off screening without creating a customer or configuring a workflow, using quickscan.submit, quickscan.detail and quickscan.hits.
• Web3 Transaction Screening — blockchain transaction screening with WEB3_TRANSACTION_EVENT.
• Webhook Integration — console setup, request signing, response handling, Decision Webhooks and troubleshooting.

Next: pick a workflow