Overview

VerityPro provides KYC identity verification, address verification, enhanced due diligence (EDD), and transaction monitoring (AML) as modular APIs and SDKs. Each product is independently activatable — your integration only calls the services your compliance programme requires.

Base URL

Request format

All requests are JSON (Content-Type: application/json). Authentication uses two headers present on every call.

Authentication

VerityPro uses API key authentication. Every request must include both headers below. Retrieve your keys from the Integrations page in the VerityPro portal.

Key rotation

Rotate keys from the portal under Settings → Integration → Keys → Rotate. When the rotation runs immediately, the new key is displayed once — copy it into your secrets manager before you close the dialog. If your organisation requires approval for key rotation, the request is queued instead and the new key is not shown in that dialog; ask your approver how it will be delivered before you rotate.

Environments

Pass sandbox: true in SDK options to target the sandbox automatically. Server-side calls set the base URL manually.

Create KYC Session

Your server creates a verification session and receives back a sessionUrl. Send that URL to your customer — VerityPro hosts the entire document capture and liveness flow with your branding applied. Your API key stays server-side only.

Response

id — v2 session ID. Store this to poll status and for returning-user sessions.
attemptId — unique per evidence submission. Matches kycverification.AttemptId in every decision webhook — use it to correlate polling with webhook delivery.
kycEngineSessionId — null at creation; populated after the document step submits.
Send nextAction.sessionUrl to your customer. Sessions expire in 60 minutes.

Hosted Web Page (v2)

The recommended integration path. Use the same POST /kycintegration/v2/sessions endpoint as Create Session. The response includes nextAction.sessionUrl — redirect your user to that URL or embed it in an iframe. VerityPro renders the full verification flow with your branding. Your API key never touches the browser.

The session URL is in data.nextAction.sessionUrl in the response.

Redirect (full-page)

Iframe embed + postMessage

Poll session state anytime

Returns current status, completedSteps, currentStep, attemptId, and kycEngineSessionId. The attemptId matches kycverification.AttemptId in the decision webhook — use it to correlate polling with webhook delivery. No auth header required — the session ID is the capability.

iOS SDK

Add to your Podfile:

Then run pod install.

Requirements

• iOS 17.0+ deployment target
• Camera and FaceID usage descriptions in Info.plist
• Session token minted by your server (see Create Session)

Info.plist entries required

Result handling

The VerityResult returned in the completion block contains the outcome, completed steps, and any error details including whether the error is recoverable.

Brand customisation (optional)

Pass your logo and primary colour to show your brand inside the verification flow:

Android SDK

Add the GitHub Packages repository and dependency to your build.gradle:

Manifest permissions

Activity result launcher

Register the launcher in onCreate before the activity is started. Use VerityPro.extractResult(result) to get the typed result.

Brand customisation (optional)

Pass VpBrandConfig to show your logo and colour inside the flow:

Flutter SDK

Dart plugin bridging to the native iOS/Android SDKs — same product coverage. Installed via git dependency (not published to pub.dev).

pubspec.yaml

v2 — server-driven (recommended): pass serverSessionId from your backend and mode: VerityMode.serverDriven. The full Dart example is in the code panel.

Brand customisation: pass an optional brandConfig: VpBrandConfig(logoUrl: ..., primaryColor: ...) to show your logo and colour. The logo must be an HTTPS URL.

v1 — legacy: use mode: VerityMode.biometric (or .address / .edd) with preCreatedSessionId.

Web SDK

Install: npm install @veritypro/web-sdk

Presentation modes

Use the embedToken from your server session call. Do not pass your API key to the web SDK.

Optional: modules hint

Pass modules to pre-render the correct verification steps on the welcome screen before the backend session loads. The backend session's requestedSteps always win once fetched — this is a display hint only.

Reading the Attempt ID

The onSessionEstablished callback fires with the KYC engine session ID once created. The Attempt ID is included in the onResult payload and in every webhook for that session.

KYC Webhooks

VerityPro delivers a webhook to your registered endpoint when a KYC session reaches a terminal state. Configure the URL in Settings → Integration → Webhooks.

Payload fields

Verify the X-Veritypro-Signature header on every webhook before processing. See Verify Signature for details.

Address SDK

Address verification is triggered through the same SDK as KYC — set mode: .address (iOS) or mode = VerityMode.ADDRESS.name (Android). No separate SDK install is needed.

SDK options for address verification

Address Server API

Add ADDRESS to the steps array when creating a session. This works standalone or combined with KYC in a single session.

The response nextAction.sessionUrl takes the customer through the address proof upload step. A webhook fires with event address_completed when done.

Trigger EDD

Enhanced Due Diligence (EDD) is triggered when your risk programme identifies a customer requiring deeper scrutiny — typically after a high-risk transaction flag or on a scheduled review cycle. The customer must have an Approved KYC session in the system first.

No request body required. Pass your internal customer identifier as the vendorData query parameter — it must match the value used at KYC onboarding. Returns 200 on success or 404 if no approved KYC session exists for that customer.

EDD can also be included as a step at session creation — pass steps: ["DOCUMENT", "BIOMETRIC", "EDD"] to run it as part of the onboarding flow. A webhook fires with event edd_completed when the case is resolved.

EDD Status

Poll the session state to track EDD progress. The session also receives an edd_completed webhook when the case is resolved.

Response (EDD fields)

EDD reviews are completed by your compliance team in the VerityPro case management portal.

Process Transaction

Submit transactions to VerityPro's AML engine for real-time risk scoring. Each transaction is checked against velocity rules, sanctions screening, and ML-based anomaly detection. A risk decision is returned synchronously.

Response

Decision values: PASS | REVIEW | DECLINED. Treat REVIEW as a soft block — hold the transaction pending analyst review. DECLINED is a hard block.

Step-Up Biometric Authentication

Re-verify a returning user's identity using face liveness + face match against the template enrolled during KYC onboarding. Use this for risk-triggered moments — high-value transactions, new-device logins, suspicious activity — rather than full re-onboarding. The subject must have completed a liveness-verified KYC session with the BIOMETRIC module before step-up is available.

Authentication: x-api-key only (JWT is not accepted on step-up endpoints). The subjectId must exactly match the vendorData value used at KYC onboarding.

1 — Create a challenge

Returns challengeId (your primary reference, valid 300s, max 3 attempts) and hostedUrl — send this link to your customer by SMS, email, or deep-link. VerityPro renders the liveness UI. A 422 means the subject has no enrolled biometric template — route to full KYC first.

2 — Get AWS Rekognition credentials (native SDK path only)

Only needed for the native mobile SDK path (you embed the AWS Face Liveness widget directly). Returns livenessSessionId, region, and short-lived AWS credentials — pass all of them to the AWS Amplify Face Liveness widget in your app. Skip this step when using the hosted URL path.

3 — Complete after liveness (native SDK path only)

Verdicts

Webhook Event Types

VerityPro delivers events to your registered HTTPS endpoint. Configure the URL and secret in Settings → Integration → Webhooks.

Your endpoint must return HTTP 200 within 10 seconds. Failed deliveries are retried with exponential backoff for up to 24 hours.

Verify Webhook Signature

Every webhook request carries two headers: X-Veritypro-Signature, an HMAC-SHA512 signature, and X-Veritypro-Timestamp, the unix epoch seconds the payload was signed at. Always verify both before processing the payload.

The signature is computed as HMAC-SHA512(webhookSecret, "{timestamp}.{rawBody}") — the timestamp header value, a literal dot, then the raw request body bytes before JSON parsing. It is encoded as lowercase hex, 128 characters, with no prefix.

Result Types

VerityOutcome

VerityVerificationError

Error Codes

HTTP errors use standard status codes. The response body contains a typed error payload.

Error response body