API Reference - Verifow

Introduction

Verifow is an enterprise-grade Anti-Money Laundering (AML) and Combating the Financing of Terrorism (CFT) platform built for African financial institutions. Our API enables you to:

Screen transactions through a multi-layer compliance pipeline in under 200ms
Verify identities via BVN, NIN, and biometric liveness checks
Onboard businesses with CAC lookup, director verification, and beneficial owner screening
Monitor compliance via real-time dashboards and webhook notifications

This guide covers everything you need to integrate:

Authentication
Transaction Screening
KYC Verification
KYB Verification
Direct Lookup
Liveness Check
How Screening Works
Tenant Configuration
Rules
Cases
Reports
Watchlists
Interdictions
Dashboard
Customers
Behavioral Profiles
Network
Compliance
AI Assist
Engines
Countries
Webhooks
Error Handling

Authentication

The API supports two authentication methods. All endpoints (except /health) require authentication.

Method 1: Dashboard Session (HttpOnly Cookies)

Used when calling the API from the dashboard on behalf of a logged-in user. POST /api/v1/auth/login validates the email and password and — on success — sets two HttpOnly cookies:

Cookie	Purpose
`ratel_access_token`	Short-lived access token, sent automatically with every request
`ratel_refresh_token`	Long-lived refresh token, used only by `POST /api/v1/auth/refresh`

Tokens are never returned in the response body and are not readable from JavaScript — the browser sends the cookies automatically. MFA challenge flow: if the tenant’s MFA policy requires it, login does not set the cookies immediately. Instead the response carries mfaRequired (or mfaSetupRequired) with a short-lived tempToken. Submit the TOTP code together with the tempToken to POST /api/v1/auth/mfa/verify — or enrol via POST /api/v1/auth/mfa/setup — to complete the login and receive the cookie pair. Session lifecycle:

POST /api/v1/auth/refresh — reads the ratel_refresh_token cookie and issues a fresh access/refresh cookie pair. Refresh tokens rotate: the old refresh token is invalidated on every refresh.
POST /api/v1/auth/logout — ends the session and clears the cookies.

Method 2: API Key (Backend Integrations)

Used for server-to-server integrations from your core banking system.

X-API-Key: rk_live_a1b2c3d4e5f6g7h8i9j0

Create keys with POST /api/v1/auth/api-keys or from Dashboard → API Keys. The plaintext key is returned exactly once in the creation response — store it securely; only a hash is persisted. API keys are tenant-scoped and carry the same permissions as the user who created them. Revoke a key with DELETE /api/v1/auth/api-keys/:id.

Keep your credentials secret. Never expose tokens or API keys in client-side code (mobile apps, browser JavaScript). All API calls must originate from your backend servers.

Transaction Screening

Screen Transaction

POST /api/v1/transactions/screen Submit a single transaction for real-time AML/CFT screening. The response includes the final outcome, risk breakdown per engine, triggered rules, and recommended actions. Request Body

Field	Type	Required	Description
`externalId`	`string`	✅	Your unique transaction reference. Used for idempotency — re-submitting the same ID returns `409 Conflict` instead of re-screening, so retries are safe.
`type`	`string`	✅	`CASH_DEPOSIT`, `CASH_WITHDRAWAL`, `TRANSFER`, `INTERNATIONAL_TRANSFER`, `POS`, `ATM`, `MOBILE`, `USSD`, `INTERNET_BANKING`
`channel`	`string`	✅	`BRANCH`, `MOBILE_APP`, `INTERNET_BANKING`, `POS_TERMINAL`, `ATM`, `USSD`, `AGENT`, `API`
`amount`	`number`	✅	Amount in base currency unit (e.g. `5000000` = ₦5M).
`currency`	`string`		`NGN`, `USD`, `GBP`, `EUR`, `GHS`, `XOF`, `KES`, `ZAR`. Defaults to `NGN`.
`senderAccountNumber`	`string`	✅	Sender’s bank account number (NUBAN, 10 digits).
`senderBvn`	`string`		Sender’s BVN. Strongly recommended — enables KYC Verification scoring.
`senderKycStatus`	`string`		`NONE`, `PENDING`, `IN_PROGRESS`, `VERIFIED`, `REJECTED`, `EXPIRED`. Overrides DB lookup in HYBRID/EXTERNAL modes.
`senderKycTier`	`string`		`TIER_1`, `TIER_2`, `TIER_3`. Required in EXTERNAL mode; enables CBN tier-based limits in rule engines.
`senderKycVerifiedAt`	`string`		ISO 8601 timestamp of last KYC verification.
`senderKycExternalRef`	`string`		Internal KYC reference (e.g. `CORE-BANK-KYC-78432`).
`senderKybStatus`	`string`		`NONE`, `PENDING`, `IN_PROGRESS`, `VERIFIED`, `REJECTED`. For business transactions; bypasses Verifow KYB lookup when `VERIFIED`.
`senderName`	`string`	✅	Sender’s full name. Screened against global sanctions & PEP lists.
`senderBankCode`	`string`		Sender’s bank CBN code (e.g. `"058"` for GTBank).
`receiverAccountNumber`	`string`		Receiver’s account number.
`receiverName`	`string`		Receiver’s full name. Also screened if provided.
`receiverBvn`	`string`		Receiver’s BVN.
`receiverKycStatus`	`string`		`NONE`, `PENDING`, `IN_PROGRESS`, `VERIFIED`, `REJECTED`, `EXPIRED`.
`receiverKycVerifiedAt`	`string`		ISO 8601 timestamp of last KYC verification.
`receiverKycExternalRef`	`string`		Internal KYC reference for the receiver.
`receiverBankCode`	`string`		Receiver’s bank CBN code.
`receiverCountry`	`string`		ISO 3166-1 alpha-2 code (e.g. `"NG"`, `"US"`). Triggers FTR if ≠ `NG`.
`narration`	`string`		Transaction description. Scanned for high-risk keywords.
`deviceId`	`string`		Device fingerprint. Enables behavioral anomaly detection.
`ipAddress`	`string`		Client IP address. Enables geo-anomaly detection.
`latitude`	`number`		GPS latitude. Used for geo-anomaly detection.
`longitude`	`number`		GPS longitude. Used for geo-anomaly detection.
`timestamp`	`string`	✅	ISO 8601 (e.g. `"2026-05-08T12:00:00Z"`).
`metadata`	`object`		Optional metadata — behavioral context (see below) and business-transaction fields (see Business Transactions).

Currency conversion: All ₦-denominated CBN thresholds (CTR, tier limits, structuring sums) are evaluated against the NGN-equivalent amount, converted with your tenant’s configured FX rates (PATCH /api/v1/tenants/me/fx-rates). For non-NGN transactions the applied conversion is echoed in riskBreakdown[].fx. If no rate is configured for a currency, the raw amount is still evaluated, but the verdict carries the FX_RATE_MISSING action — a foreign currency is never silently treated as 1:1 NGN.

Behavioral Metadata The behavioral engine scores each account from the context you forward — send what your core banking already knows. Rich context means sharper detection and fewer false alarms.

Field	Requirement	Why it matters
`metadata.ipAddress`	Recommended	Real client IP — geo, VPN/datacenter detection, IP blacklist
`metadata.deviceId`	Recommended	Device fingerprint — device-farming and account-sharing detection
`metadata.userAgent`	Recommended	Real app/browser UA — bot/script detection, device parsing
`metadata.email`	Recommended	Customer email from your records — email blacklist, disposable-domain detection, shared-email rings
`metadata.phoneNumber`	Optional	Shared-phone fraud-ring detection
`metadata.httpReferer`	Optional	Your app/channel URL — prevents empty-referer false positives

Only forward real values — never placeholders. Missing fields simply degrade that signal; synthetic values actively poison the scoring.

Example Request — Individual Transaction

curl -X POST /api/v1/transactions/screen \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "TXN-2026-001",
    "type": "TRANSFER",
    "channel": "MOBILE_APP",
    "amount": 5000000,
    "currency": "NGN",
    "senderAccountNumber": "0123456789",
    "senderBvn": "22012345678",
    "senderKycStatus": "PENDING",
    "senderKycTier": "TIER_1",
    "senderKycVerifiedAt": "2026-05-01T10:00:00Z",
    "senderKycExternalRef": "CORE-BANK-KYC-78432",
    "senderName": "John Doe",
    "senderBankCode": "058",
    "receiverAccountNumber": "9876543210",
    "receiverBvn": "22087654321",
    "receiverName": "Jane Smith",
    "receiverBankCode": "033",
    "receiverKycStatus": "VERIFIED",
    "receiverKycVerifiedAt": "2026-04-15T10:00:00Z",
    "receiverKycExternalRef": "CORE-BANK-KYC-99123",
    "receiverCountry": "NG",
    "narration": "Payment for goods",
    "deviceId": "device_abc123",
    "ipAddress": "102.89.47.12",
    "latitude": 6.5244,
    "longitude": 3.3792,
    "timestamp": "2026-05-08T12:00:00Z",
    "metadata": {
      "entityType": "INDIVIDUAL"
    }
  }'

const response = await fetch("/api/v1/transactions/screen", {
  method: "POST",
  headers: {
    "X-API-Key": "rk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: "TXN-2026-001",
    type: "TRANSFER",
    channel: "MOBILE_APP",
    amount: 5000000,
    currency: "NGN",
    senderAccountNumber: "0123456789",
    senderBvn: "22012345678",
    senderKycStatus: "PENDING",
    senderKycTier: "TIER_1",
    senderKycVerifiedAt: "2026-05-01T10:00:00Z",
    senderKycExternalRef: "CORE-BANK-KYC-78432",
    senderName: "John Doe",
    senderBankCode: "058",
    receiverAccountNumber: "9876543210",
    receiverBvn: "22087654321",
    receiverName: "Jane Smith",
    receiverBankCode: "033",
    receiverKycStatus: "VERIFIED",
    receiverKycVerifiedAt: "2026-04-15T10:00:00Z",
    receiverKycExternalRef: "CORE-BANK-KYC-99123",
    receiverCountry: "NG",
    narration: "Payment for goods",
    deviceId: "device_abc123",
    ipAddress: "102.89.47.12",
    latitude: 6.5244,
    longitude: 3.3792,
    timestamp: "2026-05-08T12:00:00Z",
    metadata: {
      entityType: "INDIVIDUAL",
    },
  }),
});

const result = await response.json();
console.log(result.data.outcome); // "APPROVE" | "REVIEW" | "ESCALATE" | "BLOCK"

import requests

response = requests.post(
    "/api/v1/transactions/screen",
    headers={
        "X-API-Key": "rk_live_...",
        "Content-Type": "application/json"
    },
    json={
        "externalId": "TXN-2026-001",
        "type": "TRANSFER",
        "channel": "MOBILE_APP",
        "amount": 5000000,
        "currency": "NGN",
        "senderAccountNumber": "0123456789",
        "senderBvn": "22012345678",
        "senderKycStatus": "PENDING",
        "senderKycTier": "TIER_1",
        "senderKycVerifiedAt": "2026-05-01T10:00:00Z",
        "senderKycExternalRef": "CORE-BANK-KYC-78432",
        "senderName": "John Doe",
        "senderBankCode": "058",
        "receiverAccountNumber": "9876543210",
        "receiverBvn": "22087654321",
        "receiverName": "Jane Smith",
        "receiverBankCode": "033",
        "receiverKycStatus": "VERIFIED",
        "receiverKycVerifiedAt": "2026-04-15T10:00:00Z",
        "receiverKycExternalRef": "CORE-BANK-KYC-99123",
        "receiverCountry": "NG",
        "narration": "Payment for goods",
        "deviceId": "device_abc123",
        "ipAddress": "102.89.47.12",
        "latitude": 6.5244,
        "longitude": 3.3792,
        "timestamp": "2026-05-08T12:00:00Z",
        "metadata": {
            "entityType": "INDIVIDUAL"
        }
    }
)

result = response.json()
print(result["data"]["outcome"])  # "APPROVE" | "REVIEW" | "ESCALATE" | "BLOCK"

Business Transactions (KYB)

For corporate senders, set metadata.entityType to "BUSINESS" and provide the company’s CAC registration number in metadata.senderRcNumber. The platform runs the transaction through the KYB identity-risk engine in addition to KYC and sanctions screening. If your bank has already verified the business outside of Verifow, send senderKybStatus: "VERIFIED" to bypass the Verifow KYB lookup. You should still send the sender’s KYC fields (senderKycStatus, senderKycTier, senderKycVerifiedAt, senderKycExternalRef) when available, because authorized signatories and directors may still be evaluated under individual KYC rules. Example Request — Business Transaction

{
  "externalId": "TXN-2026-BIZ-001",
  "type": "TRANSFER",
  "channel": "INTERNET_BANKING",
  "amount": 25000000,
  "currency": "NGN",
  "senderAccountNumber": "0123456789",
  "senderBvn": "22012345678",
  "senderName": "Acme Nigeria Ltd",
  "senderBankCode": "058",
  "senderKycStatus": "VERIFIED",
  "senderKycTier": "TIER_3",
  "senderKycVerifiedAt": "2026-05-01T10:00:00Z",
  "senderKycExternalRef": "CORE-BANK-KYC-78432",
  "senderKybStatus": "VERIFIED",
  "receiverAccountNumber": "9876543210",
  "receiverName": "Jane Smith",
  "receiverBankCode": "033",
  "receiverCountry": "NG",
  "narration": "Invoice payment",
  "timestamp": "2026-05-08T12:00:00Z",
  "metadata": {
    "entityType": "BUSINESS",
    "senderRcNumber": "RC123456"
  }
}

Business Screening Payload Fields

Field	Type	Required	Description
`senderKycStatus`	`string`	✅	`NONE`, `PENDING`, `IN_PROGRESS`, `VERIFIED`, `REJECTED`, `EXPIRED`. Required in EXTERNAL mode; asserts the sender’s individual KYC status.
`senderKycTier`	`string`	✅	`TIER_1`, `TIER_2`, `TIER_3`. Required in EXTERNAL mode; enables CBN tier-based limits.
`senderKycVerifiedAt`	`string`		ISO 8601 timestamp of last KYC verification.
`senderKycExternalRef`	`string`		Internal KYC reference for audit trail.
`senderKybStatus`	`string`	✅	`NONE`, `PENDING`, `IN_PROGRESS`, `VERIFIED`, `REJECTED`. For business transactions; asserts the corporate KYB status.
`metadata.entityType`	`string`	✅	Must be `"BUSINESS"` to trigger KYB screening.
`metadata.senderRcNumber`	`string`	✅	CAC registration number (e.g. `"RC123456"`).

Regulatory transparency: When you assert senderKycStatus or senderKybStatus in the payload, you are attesting that your bank has independently verified the customer or business. Verifow will rely on these assertions instead of performing its own lookup when the tenant is configured for HYBRID or EXTERNAL mode.

If senderKybStatus is omitted for a business transaction, Verifow will attempt a local KYB lookup using metadata.senderRcNumber. If no KYB record exists, the transaction will be scored as high risk.

Example Response — 200 OK (REVIEW)

{
  "success": true,
  "data": {
    "transactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
    "externalId": "TXN-2026-001",
    "outcome": "BLOCK",
    "riskLevel": "HIGH",
    "aggregateScore": 100,
    "actions": ["NOTIFY_OFFICER", "CREATE_CASE"],
    "riskBreakdown": [
      {
        "category": "Regulatory Compliance",
        "score": 0,
        "outcome": "APPROVE",
        "rulesTriggered": 0,
        "latencyMs": 3
      },
      {
        "category": "Global Sanctions Screening",
        "score": 0,
        "outcome": "APPROVE",
        "rulesTriggered": 0,
        "latencyMs": 97
      },
      {
        "category": "KYC Verification",
        "score": 100,
        "outcome": "BLOCK",
        "rulesTriggered": 1,
        "latencyMs": 0
      },
      {
        "category": "Custom Rules",
        "score": 0,
        "outcome": "APPROVE",
        "rulesTriggered": 0,
        "latencyMs": 178
      },
      {
        "category": "Decision Engine",
        "score": 0,
        "outcome": "APPROVE",
        "rulesTriggered": 0,
        "latencyMs": 9
      },
      {
        "category": "Behavioral Analysis",
        "score": 0,
        "outcome": "APPROVE",
        "rulesTriggered": 1,
        "latencyMs": 92
      }
    ],
    "triggeredRules": [
      {
        "name": "KYC Status Non-Verified",
        "category": "KYC Verification",
        "riskScore": 100,
        "details": "No KYC record found for sender (BVN: 22012345678)",
        "createdBy": null,
        "kycSource": "DATABASE",
        "kycExternalRef": null
      }
    ],
    "totalLatencyMs": 398
  }
}

Example Response — 200 OK (BLOCK with Sanctions Hit)

{
  "success": true,
  "data": {
    "transactionId": "20442e74-c039-4640-aadd-5ee5d9024b33",
    "externalId": "TXN-2026-002",
    "outcome": "BLOCK",
    "riskLevel": "CRITICAL",
    "aggregateScore": 95,
    "actions": [
      "CREATE_CASE",
      "NOTIFY_COMPLIANCE",
      "GENERATE_SAR",
      "ENHANCED_DUE_DILIGENCE"
    ],
    "riskBreakdown": [
      {
        "category": "Regulatory Compliance",
        "score": 100,
        "outcome": "BLOCK",
        "rulesTriggered": 2,
        "latencyMs": 1
      },
      {
        "category": "Global Sanctions Screening",
        "score": 95,
        "outcome": "BLOCK",
        "rulesTriggered": 2,
        "latencyMs": 97
      }
    ],
    "triggeredRules": [
      {
        "name": "Structuring Detection",
        "category": "Regulatory Compliance",
        "riskScore": 80,
        "details": "Potential structuring: 4 transactions totaling ₦11,000,000.00 in 24h",
        "createdBy": null
      },
      {
        "name": "Sender \"John Doe\" matches global sanctions list",
        "category": "Global Sanctions Screening",
        "riskScore": 95,
        "details": "Matched: \"LAM, John Top\" (95.0% confidence) | Source: US OFAC Sanctions | Programs: GLOMAG",
        "createdBy": null
      }
    ],
    "totalLatencyMs": 398
  }
}

Example Response — 400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "amount", "message": "amount must be a positive number" }
    ]
  }
}

Example Response — 409 Conflict (Duplicate externalId)

{
  "success": false,
  "error": {
    "code": "DUPLICATE_EXTERNAL_ID",
    "message": "This externalId has already been processed",
    "data": {
      "transactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
      "outcome": "BLOCK",
      "riskLevel": "HIGH",
      "aggregateScore": 100
    }
  }
}

Idempotency: externalId is unique per tenant. Re-submitting the same externalId returns 409 Conflict — with the original verdict embedded in error.data — instead of re-screening. This makes retries after network failures safe: send the identical payload again and either you get the fresh verdict (200) or the duplicate guard tells you it was already processed (409).

List Transactions

GET /api/v1/transactions Retrieve a paginated, tenant-scoped history of all screened transactions. Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`1`	Page number
`limit`	`integer`	`20`	Items per page
`outcome`	`string`	—	Filter by `APPROVE`, `REVIEW`, `ESCALATE`, `BLOCK`
`riskLevel`	`string`	—	Filter by `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
`type`	`string`	—	Filter by transaction type
`search`	`string`	—	Free-text search

Example Response — 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "fae50ecb-d997-4700-bae7-49650678bb06",
        "externalId": "TXN-0791-389803",
        "type": "TRANSFER",
        "channel": "MOBILE_APP",
        "amount": "5000000",
        "currency": "NGN",
        "senderAccountNumber": "0123456789",
        "senderName": "John Doe",
        "receiverName": "Jane Smith",
        "receiverCountry": "NG",
        "transactionTimestamp": "2026-05-16T12:00:00Z",
        "verdict": {
          "outcome": "BLOCK",
          "riskLevel": "CRITICAL",
          "aggregateScore": 95,
          "totalLatencyMs": 145
        },
        "createdAt": "2026-05-16T12:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Get Transaction Detail

GET /api/v1/transactions/:id Retrieve the full screening result for a single transaction, including the complete verdict with engine breakdowns. Path Parameters

Parameter	Type	Description
`id`	`string`	Transaction UUID

Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "fae50ecb-d997-4700-bae7-49650678bb06",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "externalId": "TXN-0791-389803",
    "type": "TRANSFER",
    "channel": "MOBILE_APP",
    "amount": "5000000",
    "currency": "NGN",
    "senderAccountNumber": "0123456789",
    "senderBvn": "22012345678",
    "senderName": "John Doe",
    "senderBankCode": null,
    "receiverAccountNumber": "9876543210",
    "receiverBvn": null,
    "receiverName": "Jane Smith",
    "receiverBankCode": null,
    "receiverCountry": "NG",
    "narration": "Payment for goods",
    "deviceId": null,
    "ipAddress": null,
    "latitude": null,
    "longitude": null,
    "transactionTimestamp": "2026-05-16T12:00:00Z",
    "metadata": null,
    "createdAt": "2026-05-16T12:00:00Z",
    "verdict": {
      "id": "vtx_001",
      "transactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
      "outcome": "REVIEW",
      "riskLevel": "MEDIUM",
      "aggregateScore": 32,
      "engineVerdicts": [
        {
          "engineName": "KYC Verification",
          "score": 40,
          "outcome": "REVIEW",
          "rulesTriggered": 1,
          "latencyMs": 0
        }
      ],
      "actions": ["NOTIFY_OFFICER"],
      "totalLatencyMs": 13447,
      "processedAt": "2026-05-16T12:00:01Z"
    }
  }
}

Transaction data is immutable once screened. If you need to re-evaluate, submit a new transaction with a different externalId.

KYC Verification

KYC (Know Your Customer) verification validates individual customer identities through BVN, NIN, and biometric liveness checks against national identity providers.

KYC Application Statuses

Status	Meaning	Risk Impact
`PENDING`	Submitted, awaiting verification	Score 100, `BLOCK`
`DOCUMENT_UPLOADED`	ID documents uploaded	Score 100, `BLOCK`
`NIN_VERIFIED`	NIN check passed	Score 100, `BLOCK`
`BVN_VERIFIED`	BVN check passed	Score 100, `BLOCK`
`LIVENESS_PASSED`	Biometric liveness check passed	Score 0, `APPROVE`
`APPROVED`	Fully verified by officer	Score 0, `APPROVE`
`REJECTED`	Failed verification	Score 100, `BLOCK`
`EXPIRED`	Verification expired	Score 100, `BLOCK`

Submit KYC Application

POST /api/v1/kyc/applications Create a new KYC application for an individual customer. Request Body

Field	Type	Required	Description
`entityType`	`string`	✅	`INDIVIDUAL` or `BUSINESS`
`firstName`	`string`	✅	Applicant first name
`lastName`	`string`	✅	Applicant last name
`bvn`	`string`		Bank Verification Number (11 digits)
`nin`	`string`		National Identity Number (11 digits)
`phone`	`string`		Mobile number with country code
`email`	`string`		Email address
`dateOfBirth`	`string`		ISO 8601 date (e.g. `"1990-03-15"`)
`tier`	`string`		`TIER_1`, `TIER_2`, or `TIER_3`. Defaults to `TIER_1`

Example Request

curl -X POST /api/v1/kyc/applications \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "INDIVIDUAL",
    "firstName": "Chinedu",
    "lastName": "Obi",
    "bvn": "22012345678",
    "nin": "12345678901",
    "phone": "+2348012345678",
    "email": "chinedu.obi@email.com",
    "dateOfBirth": "1990-03-15",
    "tier": "TIER_2"
  }'

Example Response — 201 Created

{
  "success": true,
  "data": {
    "id": "kyc_abc123",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "entityType": "INDIVIDUAL",
    "firstName": "Chinedu",
    "lastName": "Obi",
    "bvn": "22012345678",
    "nin": "12345678901",
    "phone": "+2348012345678",
    "email": "chinedu.obi@email.com",
    "dateOfBirth": "1990-03-15T00:00:00Z",
    "status": "PENDING",
    "riskLevel": null,
    "assignedTo": null,
    "notes": null,
    "createdAt": "2026-05-16T08:00:00Z",
    "updatedAt": "2026-05-16T08:00:00Z"
  }
}

List KYC Applications

GET /api/v1/kyc/applications Query Parameters

Parameter	Type	Default	Description
`status`	`string`	—	Filter by status
`page`	`integer`	`1`	Page number
`limit`	`integer`	`20`	Items per page

Get KYC Application

GET /api/v1/kyc/applications/:id Retrieve a KYC application with full verification results and uploaded documents. Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "kyc_abc123",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "entityType": "INDIVIDUAL",
    "status": "BVN_VERIFIED",
    "firstName": "Chinedu",
    "lastName": "Obi",
    "bvn": "22012345678",
    "nin": "12345678901",
    "phone": "+2348012345678",
    "email": "chinedu.obi@email.com",
    "address": "12 Lagos Street, Lagos",
    "dateOfBirth": "1990-03-15T00:00:00Z",
    "riskLevel": null,
    "assignedTo": null,
    "notes": null,
    "createdAt": "2026-05-16T08:00:00Z",
    "updatedAt": "2026-05-16T09:00:00Z",
    "verificationResults": [
      {
        "id": "vr_001",
        "applicationId": "kyc_abc123",
        "identityType": "BVN",
        "provider": "PREMBLY",
        "isMatch": true,
        "confidence": 0.95,
        "rawResponse": null,
        "errorMessage": null,
        "verifiedAt": "2026-05-16T09:00:00Z"
      }
    ],
    "documents": [
      {
        "id": "doc_001",
        "applicationId": "kyc_abc123",
        "documentType": "PASSPORT",
        "fileName": "passport.pdf",
        "fileUrl": "kyc-documents/passport-123.pdf",
        "fileSizeBytes": 204800,
        "mimeType": "application/pdf",
        "uploadedAt": "2026-05-16T08:30:00Z"
      }
    ]
  }
}

Update KYC Application

PATCH /api/v1/kyc/applications/:id Update applicant details on an existing KYC application. All fields are optional — send only what changes. Request Body

Field	Type	Description
`nin`	`string`	National Identity Number
`bvn`	`string`	Bank Verification Number
`email`	`string`	Email address
`phone`	`string`	Mobile number with country code
`dateOfBirth`	`string`	ISO 8601 date
`occupation`	`string`	Applicant occupation
`monthlyIncomeRange`	`string`	`0-100k`, `100k-500k`, `500k-1m`, `1m-5m`, `5m+`
`sourceOfFunds`	`string`	`SALARY`, `BUSINESS`, `INVESTMENTS`, `INHERITANCE`, `OTHER`
`segment`	`string`	`RETAIL`, `SME`, `CORPORATE`, `HNW`
`residentialState`	`string`	State of residence
`residentialCountry`	`string`	Country of residence

Verify BVN

POST /api/v1/kyc/applications/:id/verify-bvn Verify the applicant’s BVN against the configured identity provider (embedded or BYOL). Path Parameters

Parameter	Type	Description
`id`	`string`	KYC Application UUID

Request Body

Field	Type	Required	Description
`bvn`	`string`	✅	BVN to verify (11 digits)
`firstName`	`string`	✅	First name for cross-match
`lastName`	`string`	✅	Last name for cross-match
`dateOfBirth`	`string`	✅	Date of birth for cross-match

Example Request

curl -X POST /api/v1/kyc/applications/kyc_abc123/verify-bvn \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "22012345678",
    "firstName": "Chinedu",
    "lastName": "Obi",
    "dateOfBirth": "1990-03-15"
  }'

Example Response — 200 OK

{
  "success": true,
  "data": {
    "isMatch": true,
    "confidence": 0.95,
    "provider": "PREMBLY",
    "providerSource": "EMBEDDED",
    "newStatus": "BVN_VERIFIED"
  }
}

Verify NIN

POST /api/v1/kyc/applications/:id/verify-nin Verify the applicant’s NIN against the configured identity provider. Request Body

Field	Type	Required	Description
`nin`	`string`	✅	NIN to verify (11 digits)
`firstName`	`string`	✅	First name for cross-match
`lastName`	`string`	✅	Last name for cross-match
`dateOfBirth`	`string`	✅	Date of birth for cross-match

Example Response — 200 OK

{
  "success": true,
  "data": {
    "isMatch": true,
    "confidence": 0.94,
    "provider": "PREMBLY",
    "providerSource": "EMBEDDED",
    "newStatus": "NIN_VERIFIED"
  }
}

Liveness Check

POST /api/v1/kyc/applications/:id/liveness-check Run a biometric liveness detection and face-match check. This verifies that the applicant is a real person (not a photo or video spoof) and optionally matches their selfie against an uploaded ID document.

How It Works

Liveness Detection: The provider analyzes a selfie image to detect presentation attacks (printed photos, screens, masks, deepfakes).
Face Match (optional): If a document image is provided, the system compares the selfie face against the document photo.
Status Update: On success, the application status advances to LIVENESS_PASSED.

When to Use

Workflow	When to Call
Standard KYC	After BVN/NIN verification, before officer approval
High-risk onboarding	As a mandatory step for politically exposed persons
Re-verification	When KYC expires and the customer needs to re-verify

Path Parameters

Parameter	Type	Description
`id`	`string`	KYC Application UUID

Request Body

Field	Type	Required	Description
`selfieImageBase64`	`string`	✅	Base64-encoded selfie image (JPEG/PNG). Must show the applicant’s full face with good lighting.
`documentImageBase64`	`string`		Base64-encoded ID document image (passport, driver’s license, national ID). Used for face-match comparison.
`challengeType`	`string`		`passive` (default), `blink`, or `turn_head`. Active challenges require `frames`.
`frames`	`array`		Active-challenge frames (blink/turn-head sequences) for the local liveness service. Omit for the standard passive check.

Example Request

curl -X POST /api/v1/kyc/applications/kyc_abc123/liveness-check \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "selfieImageBase64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
    "documentImageBase64": "/9j/4AAQSkZJRgABAQEASABIAAD..."
  }'

Example Response — 200 OK (Pass)

{
  "success": true,
  "data": {
    "isLive": true,
    "confidence": 0.97,
    "faceMatch": true,
    "faceMatchConfidence": 0.92,
    "provider": "PREMBLY",
    "providerSource": "EMBEDDED",
    "newStatus": "LIVENESS_PASSED"
  }
}

Example Response — 200 OK (Fail — Spoof Detected)

{
  "success": true,
  "data": {
    "isLive": false,
    "confidence": 0.12,
    "faceMatch": false,
    "faceMatchConfidence": 0.0,
    "provider": "PREMBLY",
    "providerSource": "EMBEDDED",
    "newStatus": "PENDING"
  }
}

A failed liveness check does not automatically reject the application. The status remains PENDING (or its previous state) so a compliance officer can review and decide whether to request a retry or reject.

Combined Biometric Verification

POST /api/v1/kyc/applications/:id/biometric-verify Runs liveness first (local, free) and only then the BVN registry-photo face match (paid provider call) using the same selfie — a failed anti-spoof check never burns a paid call. One selfie, one API call, billed as a single liveness check. The request body is the same as the liveness check above. Returns a single decision — PASSED, FAILED_LIVENESS, or FAILED_MATCH — plus a structured reasonCode for client retry guidance: NO_FACE, MULTIPLE_FACES, CHALLENGE_FAILED, SPOOF_SUSPECTED, LIVENESS_FAILED, NO_MATCH, LIVENESS_ONLY.

Face Match (BVN Registry)

POST /api/v1/kyc/applications/:id/face-match Matches a live selfie against the applicant’s BVN registry photo via the identity provider chain. The comparison happens provider-side — the registry photo is never stored. Requires a verified BVN on the application. Billed per call like a liveness check; the result is persisted as a FACE_MATCH entry in the application’s evidence trail. Request Body

Field	Type	Required	Description
`selfieImageBase64`	`string`	✅	Base64-encoded selfie image (JPEG/PNG)

Tier Requirements & Upgrade

Endpoint	Description
`GET /api/v1/kyc/applications/:id/tier-requirements?targetTier=TIER_2`	The requirements an application must meet to move to the target tier
`POST /api/v1/kyc/applications/:id/upgrade-tier`	Upgrade the application’s tier. Body: `{ "tier": "TIER_2" }` — one of `TIER_1`, `TIER_2`, `TIER_3`

Risk History

Endpoint	Description
`GET /api/v1/kyc/applications/:id/risk-history`	Risk-level change history for a single application
`GET /api/v1/kyc/risk-changes`	Tenant-wide KYC risk changes. Filters: `level`, `source`, `from`, `to`, `page`, `limit`

KYC Provider Configuration

Manage the identity-provider chain used for BVN/NIN verification and biometric checks.

Endpoint	Description
`GET /api/v1/kyc/providers/config`	Current identity-provider configuration
`PATCH /api/v1/kyc/providers/config`	Update provider priority and circuit-breaker settings
`GET /api/v1/kyc/providers/health`	Health status of each configured provider
`GET /api/v1/kyc/providers/circuit-breakers`	Circuit-breaker state per provider

PATCH /kyc/providers/config Request Body

Field	Type	Required	Description
`kycProviderPriority`	`array`	✅	Ordered list of providers to try
`circuitBreakerEnabled`	`boolean`		Enable/disable provider circuit breakers
`circuitBreakerFailureThreshold`	`number`		Failures before a breaker opens
`circuitBreakerCooldownMs`	`number`		Cooldown (ms) before retrying an open breaker

Approve KYC Application

PATCH /api/v1/kyc/applications/:id/approve Final approval of a KYC application. Requires BANK_ADMIN or COMPLIANCE_OFFICER role. Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "kyc_abc123",
    "status": "APPROVED",
    "riskLevel": "LOW",
    "notes": "All documents verified. BVN and NIN match.",
    "updatedAt": "2026-05-16T10:00:00Z"
  }
}

Approving a KYC application updates the customer’s risk profile. Future transactions from this customer will reflect the APPROVED status (score 0, no KYC-related risk).

Reject KYC Application

PATCH /api/v1/kyc/applications/:id/reject Reject a KYC application that fails verification. Requires BANK_ADMIN or COMPLIANCE_OFFICER role. Request Body

Field	Type	Required	Description
`reason`	`string`	✅	Reason for rejection

Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "kyc_abc123",
    "status": "REJECTED",
    "riskLevel": "HIGH",
    "notes": "BVN name mismatch. Uploaded document appears fraudulent.",
    "updatedAt": "2026-05-16T10:00:00Z"
  }
}

KYB Verification

KYB (Know Your Business) verifies corporate entities before they transact. It integrates with the Corporate Affairs Commission (CAC) to validate company registration, verify directors through KYC identity checks, and screen beneficial owners against global sanctions lists.

KYB Application Statuses

Status	Meaning	Risk Impact
`PENDING`	Application submitted, awaiting CAC lookup	Score 40, `REVIEW`
`CAC_VERIFIED`	CAC lookup successful	Score 40, `REVIEW`
`DIRECTORS_VERIFIED`	Directors identity verified	Score 40, `REVIEW`
`BENEFICIAL_OWNERS_VERIFIED`	Beneficial owners screened	Score 100, `BLOCK`
`APPROVED`	Fully verified	Score 0, `APPROVE`
`REJECTED`	Failed verification or sanctions hit	Score 85, `BLOCK`

KYB Screening Trigger

KYB checks run automatically during transaction screening when the transaction metadata indicates a business entity:

{
  "metadata": {
    "entityType": "BUSINESS",
    "senderRcNumber": "RC123456"
  }
}

Submit KYB Application

POST /api/v1/kyc/kyb/applications Create a new KYB application for a corporate entity. Request Body

Field	Type	Required	Description
`companyName`	`string`	✅	Registered company name
`rcNumber`	`string`		CAC registration number
`tin`	`string`		Tax Identification Number
`address`	`string`		Registered business address
`incorporationDate`	`string`		ISO 8601 date
`directors`	`array`		Array of director objects
`directors[].name`	`string`	✅	Director full name
`directors[].bvn`	`string`		Director BVN
`directors[].nin`	`string`		Director NIN
`directors[].email`	`string`		Director email
`directors[].phone`	`string`		Director phone
`directors[].nationality`	`string`		Director nationality
`beneficialOwners`	`array`		Array of beneficial owner objects
`beneficialOwners[].name`	`string`	✅	Owner full name
`beneficialOwners[].percentage`	`number`	✅	Ownership percentage
`beneficialOwners[].bvn`	`string`		Owner BVN
`beneficialOwners[].nin`	`string`		Owner NIN

Example Request

curl -X POST /api/v1/kyc/kyb/applications \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Nigeria Ltd",
    "rcNumber": "RC123456",
    "tin": "12345678-0001",
    "address": "15 Broad Street, Lagos",
    "incorporationDate": "2015-06-12",
    "directors": [
      { "name": "John Doe", "bvn": "22012345678", "email": "john@acme.ng" }
    ],
    "beneficialOwners": [
      { "name": "Jane Smith", "percentage": 75, "bvn": "22087654321" }
    ]
  }'

Example Response — 201 Created

{
  "success": true,
  "data": {
    "id": "kyb_abc123",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "companyName": "Acme Nigeria Ltd",
    "rcNumber": "RC123456",
    "tin": "12345678-0001",
    "address": "15 Broad Street, Lagos",
    "incorporationDate": "2015-06-12T00:00:00Z",
    "status": "PENDING",
    "riskLevel": null,
    "directors": [
      { "name": "John Doe", "bvn": "22012345678", "email": "john@acme.ng" }
    ],
    "beneficialOwners": [
      { "name": "Jane Smith", "percentage": 75, "bvn": "22087654321" }
    ],
    "assignedTo": null,
    "notes": null,
    "createdAt": "2026-05-16T08:00:00Z",
    "updatedAt": "2026-05-16T08:00:00Z"
  }
}

Update KYB Application

PATCH /api/v1/kyc/kyb/applications/:id Update an existing KYB application. All fields are optional — send only what changes: companyName, rcNumber, tin, address, incorporationDate, businessActivity, operatingCountry, directors, beneficialOwners, notes.

Run KYB Screening

POST /api/v1/kyc/kyb/applications/:id/run-screening Runs the KYB screening pipeline for the application — CAC verification, director identity checks, and beneficial-owner sanctions screening.

Verify CAC

POST /api/v1/kyc/kyb/applications/:id/verify-cac Run a CAC lookup by RC number to fetch company details, directors, and beneficial owners. Request Body

Field	Type	Required	Description
`rcNumber`	`string`	✅	CAC registration number

Example Response — 200 OK

{
  "success": true,
  "data": {
    "found": true,
    "confidence": 0.95,
    "company": {
      "rcNumber": "RC123456",
      "companyName": "Acme Nigeria Ltd",
      "address": "15 Broad Street, Lagos",
      "registrationDate": "2015-06-12",
      "directors": [
        {
          "name": "John Doe",
          "nationality": "Nigerian",
          "appointmentDate": "2015-06-12"
        }
      ],
      "beneficialOwners": [{ "name": "Jane Smith", "percentage": 75 }]
    },
    "newStatus": "CAC_VERIFIED"
  }
}

Verify Directors

POST /api/v1/kyc/kyb/applications/:id/verify-directors Verify each director’s identity via BVN/NIN against identity providers. Request Body

Field	Type	Required	Description
`directors`	`array`	✅	Array of director verification objects
`directors[].name`	`string`	✅	Director name
`directors[].nin`	`string`		Director NIN
`directors[].bvn`	`string`		Director BVN
`directors[].verified`	`boolean`		Pre-verified flag

Example Response — 200 OK

{
  "success": true,
  "data": {
    "allVerified": true,
    "directors": [
      {
        "name": "John Doe",
        "nin": "12345678901",
        "bvn": "22012345678",
        "verified": true
      }
    ],
    "newStatus": "DIRECTORS_VERIFIED"
  }
}

Screen Beneficial Owners

POST /api/v1/kyc/kyb/applications/:id/screen-beneficial-owners Screen beneficial owners against global sanctions and PEP watchlists. Request Body

Field	Type	Required	Description
`beneficialOwners`	`array`	✅	Array of BO screening objects
`beneficialOwners[].name`	`string`	✅	Owner name
`beneficialOwners[].clean`	`boolean`	✅	Pre-screened clean flag
`beneficialOwners[].hits`	`array`		List of watchlist hits if not clean

Example Response — 200 OK

{
  "success": true,
  "data": {
    "allClean": true,
    "beneficialOwners": [{ "name": "Jane Smith", "clean": true, "hits": [] }],
    "newStatus": "BENEFICIAL_OWNERS_VERIFIED"
  }
}

Approve KYB Application

PATCH /api/v1/kyc/kyb/applications/:id/approve Requires BANK_ADMIN or COMPLIANCE_OFFICER role. Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "kyb_abc123",
    "status": "APPROVED",
    "riskLevel": "LOW",
    "updatedAt": "2026-05-16T10:00:00Z"
  }
}

Reject KYB Application

PATCH /api/v1/kyc/kyb/applications/:id/reject Requires BANK_ADMIN or COMPLIANCE_OFFICER role. Request Body

Field	Type	Required	Description
`reason`	`string`	✅	Reason for rejection

Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "kyb_abc123",
    "status": "REJECTED",
    "riskLevel": "HIGH",
    "notes": "Sanctions hit on beneficial owner Jane Smith.",
    "updatedAt": "2026-05-16T10:00:00Z"
  }
}

Direct Lookup

Verify identities and companies on demand — outside of a KYC/KYB application flow. Each lookup is charged per call from the tenant wallet at the configured verification price; a response (match or no-match) is charged, provider outages are not. Results are saved as reusable customer profiles.

BVN Lookup

POST /api/v1/lookup/bvn Verify an 11-digit BVN against the identity provider chain and save the result as a customer profile. Request Body

Field	Type	Required	Description
`idNumber`	`string`	✅	The 11-digit BVN
`firstName`	`string`		First name for cross-match
`lastName`	`string`		Last name for cross-match
`dateOfBirth`	`string`		Date of birth for cross-match

NIN Lookup

POST /api/v1/lookup/nin Verify an 11-digit NIN against the identity provider chain and save the result as a customer profile. Same request body and wallet-prepaid charging rules as the BVN lookup.

CAC Lookup

POST /api/v1/lookup/cac Look up a company by RC number in the CAC registry and save the result as a business customer profile (directors, shareholders, and beneficial owners included). Wallet-prepaid per lookup. Request Body

Field	Type	Required	Description
`rcNumber`	`string`	✅	CAC registration number

Lookup History & Saved Profiles

Endpoint	Description
`GET /api/v1/lookup/history`	Direct-lookup history (saved customer profiles). Paginated via `page`, `limit`
`GET /api/v1/lookup/customers/:id`	Get a saved customer profile

Create Application from a Lookup Profile

Endpoint	Description
`POST /api/v1/lookup/customers/:id/create-application`	Starts a KYC application pre-filled from a direct-lookup customer profile, linked via `sourceCustomerId`. Identity verifications are not copied — they re-run fresh through the normal application flow. NDPR consent is required.
`POST /api/v1/lookup/customers/:id/create-kyb-application`	Starts a KYB application pre-filled from a business customer profile (company details, directors, beneficial owners), linked via `sourceCustomerId`. CAC verification re-runs fresh in the KYB flow. NDPR consent is required.

Request Body (both endpoints)

Field	Type	Required	Description
`consentAccepted`	`boolean`	✅	Customer’s NDPR consent was obtained
`consentVersion`	`string`		Version of the consent text accepted
`tier`	`string`		`TIER_1`, `TIER_2`, or `TIER_3`

How Screening Works

Every transaction passes through multiple screening layers in sequence. The entire pipeline completes in 80–200ms (p95).

The Pipeline

Stage	Engine	Latency	What It Does
1	Validation	~5ms	Schema validation, idempotency check, persist transaction
2	Context Enrichment	~15ms	Fetch sender’s recent history, account dormancy, KYC/KYB status
3	Global Sanctions Screening	~25ms	Screen names against OFAC, UN, EU, UK, Interpol, PEP lists
4	Regulatory Compliance	~2ms	Execute 9 mandatory AML rules
5	Identity Risk (KYC)	~1ms	Evaluate sender’s KYC verification status
6	Identity Risk (KYB)	~1ms	For business transactions — evaluate KYB verification status
7	Decision Engine	~10ms	Local rule evaluation using stored AST formulas
8	Behavioral Analysis	~50ms	ML scoring for device, velocity, and geographic anomalies

Mandatory Regulatory Rules

These 9 rules are always active and cannot be disabled:

Rule	Trigger	Auto-Actions
AML-001 Cash Threshold	Cash ≥ ₦5,000,000	Generate CTR, Notify Officer
AML-002 Transfer Threshold	Transfer ≥ ₦10,000,000	Generate CTR, Notify Officer
AML-003 Structuring	Single txn ≥ 80% of threshold, OR 3+ txns in 24h exceeding threshold	Generate SAR, Create Case
AML-004 PEP Screening	Sender is a Politically Exposed Person	Enhanced Due Diligence
AML-005 Foreign Transfer	International transfer or receiver country ≠ NG	Generate FTR
AML-006 Dormant Account	No activity for ≥ 180 days	Create Case
AML-007 Rapid Succession	≥ 5 txns within 60 minutes from same account	Create Case
AML-008 KYC Tier Limit	Transaction exceeds sender’s KYC tier limit	Block, Prompt Tier Upgrade
AML-009 Near Tier Limit	Transaction at ≥80% of sender’s KYC tier limit	Review, Notify Officer

Identity Risk Scoring

Individual (KYC)

Sender KYC Status	Risk Score	Outcome
APPROVED	0	APPROVE
LIVENESS_PASSED	0	APPROVE
NIN_VERIFIED / BVN_VERIFIED / DOCUMENT_UPLOADED	100	BLOCK
PENDING	100	BLOCK
DOCUMENT_UPLOADED	100	BLOCK
NONE (no application)	100	BLOCK
EXPIRED	100	BLOCK
REJECTED	100	BLOCK

Business (KYB)

Sender KYB Status	Risk Score	Outcome
APPROVED	0	APPROVE
PENDING / CAC_VERIFIED / DIRECTORS_VERIFIED / BENEFICIAL_OWNERS_VERIFIED / DOCUMENT_UPLOADED / SCREENING_PASSED	100	BLOCK
NONE (no application)	100	BLOCK
REJECTED	100	BLOCK

KYC Trust Modes

Tenants can configure how KYC status is resolved during transaction screening:

Mode	Behavior
`STRICT`	Default. KYC records must exist in the DB. Payload KYC is ignored.
`HYBRID`	Uses payload KYC if provided, falls back to DB lookup.
`EXTERNAL`	Requires KYC status in every transaction payload. No local DB lookup.

Set the mode via PATCH /api/v1/tenants/me/kyc-config with the kycTrustMode field.

Score Aggregation

Category	Weight	Rationale
Regulatory Compliance	1.5×	Core compliance — highest authority
Identity Verification	1.3×	KYC/KYB integrity is compliance-critical
Custom Rules	1.2×	Institution-specific logic elevated above generic engines
Global Sanctions Screening	1.0×	Standard weight — severity via outcome escalation
Decision Engine	1.0×	Rule-mirroring redundancy
Behavioral Analysis	0.8×	Supplementary evidence

Score Floor Guarantee: Final Score = MAX(weighted_average, max_engine_score × 0.8) The highest-severity outcome from any engine becomes the final decision.

Tenant Configuration

Tenants manage their own configuration through dedicated self-service endpoints — there is no general GET /api/v1/tenants/me or PATCH /api/v1/tenants/me route.

Endpoint	Description
`GET /api/v1/tenants/me/alert-preferences`	Read alert routing preferences
`PATCH /api/v1/tenants/me/alert-preferences`	Update alert routing preferences
`PATCH /api/v1/tenants/me/branding`	Update branding settings
`PATCH /api/v1/tenants/me/case-escalation`	Update case-escalation rules
`GET /api/v1/tenants/me/fraud-channels`	Read fraud-channel controls
`PATCH /api/v1/tenants/me/fraud-channels`	Update fraud-channel controls
`PATCH /api/v1/tenants/me/fx-rates`	Set FX rates (`{ "rates": { "USD": 1500, ... } }`) used for NGN conversion of CBN thresholds
`PATCH /api/v1/tenants/me/interdiction-config`	Update interdiction behaviour
`PATCH /api/v1/tenants/me/kyc-config`	Update KYC configuration — `kycProviderMode` (`EMBEDDED`/`BYOL`), `kycProviderConfig`, `kycTrustMode` (`STRICT`/`HYBRID`/`EXTERNAL`), `kycFallbackMode`, `kycAutoDecision`
`POST /api/v1/tenants/me/logo`	Upload a tenant logo (`variant` query param)
`PATCH /api/v1/tenants/me/nfiu-config`	Update NFIU goAML filing configuration
`PATCH /api/v1/tenants/me/periodic-review`	Update the periodic KYC review schedule
`PATCH /api/v1/tenants/me/retention`	Update the data-retention policy
`PATCH /api/v1/tenants/me/webhooks`	Configure the outbound webhook endpoint (see Webhooks)

Rules

Tenant custom rules complement the mandatory CBN regulatory rules.

Endpoint	Description
`GET /api/v1/rules`	List tenant rules
`POST /api/v1/rules`	Create a rule
`GET /api/v1/rules/:id`	Get a rule
`PATCH /api/v1/rules/:id`	Update a rule
`DELETE /api/v1/rules/:id`	Delete a rule
`PATCH /api/v1/rules/:id/activate`	Activate a paused rule
`PATCH /api/v1/rules/:id/pause`	Pause a rule
`POST /api/v1/rules/simulate`	What-if simulation. Evaluates the given rule configuration against the tenant’s real transactions (default last 30 days, max 500) and returns fire count/rate, per-channel breakdown, and up to 10 sample firings with the exact conditions that matched. Nothing is persisted. Body: `{ "configuration": {...}, "days": 30, "limit": 500 }`
`POST /api/v1/rules/ai-draft`	Drafts a rule from a natural-language description. Body: `{ "prompt": "..." }`
`GET /api/v1/rules/tuning-suggestions`	Rule tuning suggestions from case outcomes. Attributes resolved case outcomes in the window (`days` query param) to the custom rules that triggered them and suggests `LOOSEN` / `OK` / `DORMANT` / `REVIEW` per rule. Read-only aggregation over stored verdicts.

Cases

Investigation cases are created automatically from screening verdicts (CREATE_CASE action / BLOCK outcomes) or manually.

Endpoint	Description
`GET /api/v1/cases`	Paginated, tenant-scoped case list. Filters: `status`, `type`, `priority`, `assignedTo`, `page`, `limit`
`POST /api/v1/cases`	Create a case manually
`GET /api/v1/cases/stats`	Aggregate case statistics
`GET /api/v1/cases/:id`	Get a case
`GET /api/v1/cases/:id/context`	Full investigation context for the case
`PATCH /api/v1/cases/:id/assign`	Assign the case to an officer
`PATCH /api/v1/cases/:id/status`	Update the case status
`POST /api/v1/cases/:id/notes`	Add a note to the case

Resolution Workflow

Resolutions follow a propose → approve/reject workflow:

Endpoint	Description
`POST /api/v1/cases/:id/propose-resolution`	Propose a resolution — body: `{ "resolution": "RESOLVED_TRUE_POSITIVE" \| "RESOLVED_FALSE_POSITIVE" \| "CLOSED", "note": "..." }`
`PATCH /api/v1/cases/:id/approve-resolution`	Approve the proposed resolution (optional `note`)
`PATCH /api/v1/cases/:id/reject-resolution`	Reject the proposed resolution (`reason` required)

Reports

Regulatory and management reporting.

Endpoint	Description
`GET /api/v1/reports`	List reports
`POST /api/v1/reports/ctr`	Generate a CTR (Currency Transaction Report). Body: `{ "transactionId" }`. Creates a draft CTR for a cash transaction above the CBN ₦5M reporting threshold. CTRs are also auto-generated by the `GENERATE_CTR` screening action.
`POST /api/v1/reports/sar`	Generate a SAR (Suspicious Activity Report). Body: `{ "transactionId", "narrativeSummary"?: string }`. Creates a draft SAR; approve via `PATCH /reports/:id/approve`, then file with the NFIU via `PATCH /reports/:id/file`.
`POST /api/v1/reports/ftr`	Generate an FTR (Foreign Transfer Report)
`POST /api/v1/reports/mi`	Generate a management-information (MI) report. Body: `{ "periodStart", "periodEnd" }` (ISO 8601, inclusive)
`POST /api/v1/reports/governance`	Generate a governance report. Body: `{ "periodStart", "periodEnd" }` (ISO 8601, inclusive)

Downloads

Endpoint	Description
`GET /api/v1/reports/:id/pdf`	Download report as PDF
`GET /api/v1/reports/:id/xlsx`	Download report as Excel (.xlsx)
`GET /api/v1/reports/:id/xml`	Download report as goAML XML for NFIU submission. Returns `404` for MI reports (internal-only — use xlsx/pdf).

NFIU goAML Filing

Endpoint	Description
`GET /api/v1/reports/:reportId/nfiu-filing`	NFIU goAML filing status for the report
`POST /api/v1/reports/:reportId/nfiu-filing/retry`	Retry a failed NFIU filing

Watchlists

Tenant-managed local watchlists, screened alongside the global sanctions lists.

Endpoint	Description
`GET /api/v1/watchlists`	List watchlists
`POST /api/v1/watchlists`	Create a watchlist
`GET /api/v1/watchlists/:id`	Get a watchlist
`DELETE /api/v1/watchlists/:id`	Delete a watchlist
`GET /api/v1/watchlists/:id/entries`	List entries in a watchlist
`POST /api/v1/watchlists/:id/entries`	Add an entry
`POST /api/v1/watchlists/:id/entries/bulk`	Bulk-add entries
`DELETE /api/v1/watchlists/:watchlistId/entries/:entryId`	Remove an entry
`GET /api/v1/watchlists/sync-status`	Sanctions-list sync status

Interdictions

Interdiction actions (e.g. account freezes or blocks) are queued from cases and executed against your systems.

Endpoint	Description
`GET /api/v1/interdictions`	Tenant interdiction queue (paginated; filter by `status`)
`POST /api/v1/interdictions/:actionId/execute`	Execute a `PENDING` interdiction action
`POST /api/v1/interdictions/:actionId/retry`	Retry a `FAILED` interdiction action
`GET /api/v1/cases/:caseId/interdictions`	Interdiction actions linked to a case
`POST /api/v1/cases/:caseId/interdictions/:actionId/retry`	Retry a failed case interdiction action

Dashboard

Endpoint	Description
`GET /api/v1/dashboard/summary`	Aggregated summary metrics for the tenant dashboard

Customers

Endpoint	Description
`GET /api/v1/customers/search?q=`	Search customers by account number or name
`GET /api/v1/customers/:hash/360`	Unified customer 360 view

Behavioral Profiles

Endpoint	Description
`POST /api/v1/profiles/score`	Customer behavior score (JWT or API key). Body: `{ "customerKey" }` — the sender’s account number, blind-indexed (HMAC) before lookup
`GET /api/v1/profiles/transaction/:transactionId`	Behavior profile for a transaction’s sender

Network

Endpoint	Description
`GET /api/v1/network/transaction/:transactionId`	Counterparty network for a transaction

Compliance

Endpoint	Description
`GET /api/v1/compliance/cbn`	CBN standards map with live evidence. The 11 CBN Baseline Standard areas with requirement, solution, feature deep links, and live per-tenant evidence (watchlist sync, active rules, audit-chain integrity, queue sizes). Read-only aggregation — no PII, counts and statuses only.
`GET /api/v1/compliance/health`	Tenant AML setup health score. 0–100 score across 11 setup items (active rules, periodic reviews, fraud controls, watchlists, retention, MFA, webhooks…), each with completion state and an action link.

AI Assist

Endpoint	Description
`POST /api/v1/ai/cases/:id/summary`	AI-drafted case investigation summary
`POST /api/v1/ai/sar-narrative`	AI-drafted SAR narrative (goAML)

Engines

Endpoint	Description
`GET /api/v1/engines/health`	Health status of the screening engines
`GET /api/v1/engines/config/:engine`	Read an engine’s configuration
`PATCH /api/v1/engines/config/:engine`	Update an engine’s configuration

Countries

Endpoint	Description
`GET /api/v1/countries`	List supported countries (active only unless `?all=true`)

Webhooks

Verifow sends real-time notifications to your backend for screening outcomes and case events.

Setup: Configure your webhookUrl and webhookSecret via PATCH /api/v1/tenants/me/webhooks, or in the Developer Webhooks section of the API Keys page in your Dashboard.

Events

Event	Trigger
`transaction.screened`	Every transaction screening
`verdict.blocked`	A transaction verdict is `BLOCK`
`alert.escalated`	An alert is escalated
`case.resolved`	A compliance officer marks a case as `RESOLVED_TRUE_POSITIVE`, `RESOLVED_FALSE_POSITIVE`, or `CLOSED`
`interdiction.executed`	An interdiction action executes successfully
`interdiction.failed`	An interdiction action fails
`nfiu.filing.submitted`	An NFIU goAML filing is submitted
`nfiu.filing.failed`	An NFIU goAML filing fails

Payload

{
  "event": "case.resolved",
  "timestamp": "2026-05-08T15:00:00Z",
  "data": {
    "caseId": "case_12345abcde",
    "status": "RESOLVED_FALSE_POSITIVE",
    "resolutionNote": "Customer provided valid source of funds documentation.",
    "relatedTransactionId": "TXN-2026-001",
    "updatedAt": "2026-05-08T15:00:00Z"
  }
}

Delivery Guarantees

Property	Value
Max Attempts	5
Backoff Strategy	Exponential (5s → 10s → 20s → 40s → 80s)
Request Timeout	10 seconds per attempt
Completed Job Retention	24 hours
Failed Job Retention	7 days

Your endpoint must return a 2xx status code. Any non-2xx response will trigger automatic retries. If all 5 attempts fail, the event is retained in the dead-letter queue for 7 days.

Signature Verification

When a webhookSecret is set, every webhook includes an X-Ratel-Signature: sha256=<hex> header (also mirrored as X-Signature) — an HMAC-SHA256 hash of the raw JSON body, signed with your Webhook Secret.

const crypto = require('crypto');

app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-ratel-signature'];
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (`sha256=${hash}` !== signature) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  if (event.event === 'case.resolved') {
    if (event.data.status === 'RESOLVED_FALSE_POSITIVE') {
      // Unfreeze the transaction in your system
    } else if (event.data.status === 'RESOLVED_TRUE_POSITIVE') {
      // Permanently block and escalate
    }
  }

  res.status(200).send('OK');
});

import hmac
import hashlib
import json
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Ratel-Signature', '')
    expected = 'sha256=' + hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = json.loads(request.data)

    if event['event'] == 'case.resolved':
        if event['data']['status'] == 'RESOLVED_FALSE_POSITIVE':
            # Unfreeze the transaction
            pass
        elif event['data']['status'] == 'RESOLVED_TRUE_POSITIVE':
            # Permanently block
            pass

    return 'OK', 200

Error Handling

Standard HTTP status codes indicate success or failure:

Code	Meaning	Solution
`200`	Success	Request processed successfully.
`201`	Created	Resource created successfully.
`400`	Bad Request	Check validation errors in the response body. Ensure all required fields are present.
`401`	Unauthorized	Your session cookie or API key is missing, invalid, or revoked.
`403`	Forbidden	Your role does not have permission for this action.
`409`	Conflict	Duplicate `externalId` or conflicting state.
`429`	Too Many Requests	Rate limit exceeded — implement exponential backoff.
`500`	Server Error	Unexpected error — retry with backoff.

Fail-Open Policy: If the Sanctions or Behavioral engines experience upstream downtime, Verifow implements a fail-open policy — your legitimate transactions continue processing without interruption, while partial screenings are logged for retroactive review.

Verifow — Enterprise-grade AML/CFT compliance for African financial institutions. For support, contact adams@bevars.com.

​Introduction

​Authentication

​Method 1: Dashboard Session (HttpOnly Cookies)

​Method 2: API Key (Backend Integrations)

​Transaction Screening

​Screen Transaction

​Business Transactions (KYB)

​List Transactions

​Get Transaction Detail

​KYC Verification

​KYC Application Statuses

​Submit KYC Application

​List KYC Applications

​Get KYC Application

​Update KYC Application

​Verify BVN

​Verify NIN

​Liveness Check

​How It Works

​When to Use

​Combined Biometric Verification

​Face Match (BVN Registry)

​Tier Requirements & Upgrade

​Risk History

​KYC Provider Configuration

​Approve KYC Application

​Reject KYC Application

​KYB Verification

​KYB Application Statuses

​KYB Screening Trigger

​Submit KYB Application

​Update KYB Application

​Run KYB Screening

​Verify CAC

​Verify Directors

​Screen Beneficial Owners

​Approve KYB Application

​Reject KYB Application

​Direct Lookup

​BVN Lookup

​NIN Lookup

​CAC Lookup

​Lookup History & Saved Profiles

​Create Application from a Lookup Profile

​How Screening Works

​The Pipeline

​Mandatory Regulatory Rules

​Identity Risk Scoring

​Individual (KYC)

​Business (KYB)

​KYC Trust Modes

​Score Aggregation

​Tenant Configuration

​Rules

​Cases

​Resolution Workflow

​Reports

​Downloads

​NFIU goAML Filing

​Watchlists

​Interdictions

​Dashboard

​Customers

​Behavioral Profiles

​Network

​Compliance

​AI Assist

​Engines

​Countries

​Webhooks

​Events

​Payload

​Delivery Guarantees

​Signature Verification

​Error Handling

Introduction

Authentication

Method 1: Dashboard Session (HttpOnly Cookies)

Method 2: API Key (Backend Integrations)

Transaction Screening

Screen Transaction

Business Transactions (KYB)

List Transactions

Get Transaction Detail

KYC Verification

KYC Application Statuses

Submit KYC Application

List KYC Applications

Get KYC Application

Update KYC Application

Verify BVN

Verify NIN

Liveness Check

How It Works

When to Use

Combined Biometric Verification

Face Match (BVN Registry)

Tier Requirements & Upgrade

Risk History

KYC Provider Configuration

Approve KYC Application

Reject KYC Application

KYB Verification

KYB Application Statuses

KYB Screening Trigger

Submit KYB Application

Update KYB Application

Run KYB Screening

Verify CAC

Verify Directors

Screen Beneficial Owners

Approve KYB Application

Reject KYB Application

Direct Lookup

BVN Lookup

NIN Lookup

CAC Lookup

Lookup History & Saved Profiles

Create Application from a Lookup Profile

How Screening Works

The Pipeline

Mandatory Regulatory Rules

Identity Risk Scoring

Individual (KYC)

Business (KYB)

KYC Trust Modes

Score Aggregation

Tenant Configuration

Rules

Cases

Resolution Workflow

Reports

Downloads

NFIU goAML Filing

Watchlists

Interdictions

Dashboard

Customers

Behavioral Profiles

Network

Compliance

AI Assist

Engines

Countries

Webhooks

Events

Payload

Delivery Guarantees

Signature Verification

Error Handling