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
Liveness Check
How Screening Works
Webhooks
Error Handling

Authentication

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

Method 1: Bearer Token (Dashboard Sessions)

Used when calling the API from the dashboard or on behalf of a logged-in user.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Obtain a token by calling POST /api/v1/auth/login with email and password.

Method 2: API Key (Backend Integrations)

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

X-API-Key: rk_live_a1b2c3d4e5f6g7h8i9j0

Generate API keys from Dashboard → API Keys. API keys are tenant-scoped and carry the same permissions as the user who created them.

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 -sending the same ID twice returns the cached verdict.
`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`		ISO 4217 code. 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`		`VERIFIED`, `PENDING`, `IN_PROGRESS`, `REJECTED`, `EXPIRED`, `NONE`. 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`		`VERIFIED`, `PENDING`, `IN_PROGRESS`, `REJECTED`, `EXPIRED`, `NONE`. 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`		`VERIFIED`, `PENDING`, `IN_PROGRESS`, `REJECTED`, `EXPIRED`, `NONE`.
`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 for business transactions (see KYB Screening).

Example Request — Individual Transaction

curl -X POST /api/v1/transactions/screen \
  -H "Authorization: Bearer <access_token>" \
  -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: {
    Authorization: "Bearer <access_token>",
    "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={
        "Authorization": "Bearer <access_token>",
        "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`	✅	`VERIFIED`, `PENDING`, `IN_PROGRESS`, `REJECTED`, `EXPIRED`, `NONE`. 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`	✅	`VERIFIED`, `PENDING`, `IN_PROGRESS`, `REJECTED`, `EXPIRED`, `NONE`. 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**

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

Example Response — 409 Conflict (Idempotent)

{
  "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: Sending the same externalId twice returns the cached verdict without re-screening. This makes retries safe.

List Transactions

GET /api/v1/transactions Retrieve a paginated list of all screened transactions in your tenant. Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`1`	Page number
`limit`	`integer`	`20`	Items per page (max 100)
`outcome`	`string`	—	Filter by `APPROVE`, `REVIEW`, `ESCALATE`, `BLOCK`
`type`	`string`	—	Filter by transaction type
`from`	`string`	—	ISO 8601 start date
`to`	`string`	—	ISO 8601 end date

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 "Authorization: Bearer <access_token>" \
  -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"
      }
    ]
  }
}

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 "Authorization: Bearer <access_token>" \
  -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.

Example Request

curl -X POST /api/v1/kyc/applications/kyc_abc123/liveness-check \
  -H "Authorization: Bearer <access_token>" \
  -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.

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 "Authorization: Bearer <access_token>" \
  -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"
  }
}

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"
  }
}

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 with kycTrustMode.

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.

Webhooks

Verifow sends real-time notifications to your backend when a compliance officer resolves a case linked to one of your transactions.

Setup: Configure your Webhook URL and Webhook Secret in the Developer Webhooks section of the API Keys page in your Dashboard.

Events

Event	Trigger
`case.resolved`	A compliance officer marks a case as `RESOLVED_TRUE_POSITIVE`, `RESOLVED_FALSE_POSITIVE`, or `CLOSED`

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

Every webhook includes an X-Signature header — 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-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-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 token 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: Bearer Token (Dashboard Sessions)

​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 /api/v1/kyc/applications

​Get KYC Application

​Verify BVN

​Verify NIN

​Liveness Check

​How It Works

​When to Use

​Approve KYC Application

​Reject KYC Application

​KYB Verification

​KYB Application Statuses

​KYB Screening Trigger

​Submit KYB Application

​Verify CAC

​Verify Directors

​Screen Beneficial Owners

​Approve KYB Application

​Reject KYB Application

​How Screening Works

​The Pipeline

​Mandatory Regulatory Rules

​Identity Risk Scoring

​Individual (KYC)

​Business (KYB)

​KYC Trust Modes

​Score Aggregation

​Webhooks

​Events

​Payload

​Delivery Guarantees

​Signature Verification

​Error Handling

Introduction

Authentication

Method 1: Bearer Token (Dashboard Sessions)

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 /api/v1/kyc/applications`

Get KYC Application

Verify BVN

Verify NIN

Liveness Check

How It Works

When to Use

Approve KYC Application

Reject KYC Application

KYB Verification

KYB Application Statuses

KYB Screening Trigger

Submit KYB Application

Verify CAC

Verify Directors

Screen Beneficial Owners

Approve KYB Application

Reject KYB Application

How Screening Works

The Pipeline

Mandatory Regulatory Rules

Identity Risk Scoring

Individual (KYC)

Business (KYB)

KYC Trust Modes

Score Aggregation

Webhooks

Events

Payload

Delivery Guarantees

Signature Verification

Error Handling