/api/v1 and are authenticated with either an HttpOnly session cookie (ratel_access_token, issued by POST /auth/login — tokens are never returned in the response body) or an X-API-Key: rk_live_... header for server-to-server calls.
Base URL
/api/v1
Endpoints by Module
Authentication
| Endpoint | Methods | Description |
|---|---|---|
/auth/login | POST | Log in (dashboard session) |
/auth/logout | POST | Log out and clear session |
/auth/refresh | POST | Rotate the session tokens |
/auth/me | GET | Current user profile |
/auth/change-password-request | POST | Request a password change token |
/auth/change-password | POST | Change password with token |
/auth/forgot-password | POST | Request a password reset email |
/auth/users | GET, POST | List or create users |
/auth/users/:id | PATCH, DELETE | Update or deactivate a user |
/auth/users/:id/mfa/reset | POST | Reset a user’s MFA |
/auth/api-keys | GET, POST | List keys or create an API key (server-to-server credential) |
/auth/api-keys/:id | DELETE | Revoke an API key |
/auth/mfa/setup | POST | Begin MFA setup (TOTP secret) |
/auth/mfa/verify | POST | Verify an MFA code |
/auth/mfa/enable | POST | Enable MFA for current user |
/auth/mfa/disable | POST | Disable MFA for current user |
/auth/mfa/backup-codes | POST | Generate MFA backup codes |
/auth/mfa/recovery-request | POST | Request MFA recovery |
/auth/mfa/recovery | POST | Complete MFA recovery |
/auth/mfa/policy | PATCH | Update tenant MFA policy |
Transactions
| Endpoint | Methods | Description |
|---|---|---|
/transactions/screen | POST | Screen a transaction (real-time AML verdict) |
/transactions | GET | List screened transactions |
/transactions/:id | GET | Get a transaction with its verdict |
Cases
| Endpoint | Methods | Description |
|---|---|---|
/cases | GET, POST | List investigation cases or create one |
/cases/stats | GET | Case workload statistics |
/cases/:id | GET | Get a case |
/cases/:id/context | GET | Related transactions and context |
/cases/:id/status | PATCH | Update case status |
/cases/:id/assign | PATCH | Assign case to a user |
/cases/:id/notes | POST | Add note to case |
/cases/:id/propose-resolution | POST | Propose a case resolution |
/cases/:id/approve-resolution | PATCH | Approve a proposed resolution |
/cases/:id/reject-resolution | PATCH | Reject a proposed resolution |
/cases/:caseId/interdictions | GET | List interdiction actions for a case |
/cases/:caseId/interdictions/:actionId/retry | POST | Retry a failed case interdiction |
Rules
| Endpoint | Methods | Description |
|---|---|---|
/rules | GET, POST | List or create rules |
/rules/simulate | POST | What-if rule simulation |
/rules/ai-draft | POST | AI-drafted rule from a prompt |
/rules/tuning-suggestions | GET | Rule tuning suggestions from case outcomes |
/rules/:id | GET, PATCH, DELETE | Get, update, or delete rule |
/rules/:id/activate | PATCH | Activate a rule |
/rules/:id/pause | PATCH | Pause a rule |
Watchlists
| Endpoint | Methods | Description |
|---|---|---|
/watchlists | GET, POST | List or create watchlists |
/watchlists/sync-status | GET | Watchlist provider sync status |
/watchlists/:id | GET, DELETE | Get or delete a watchlist |
/watchlists/:id/entries | GET, POST | List or add watchlist entries |
/watchlists/:id/entries/bulk | POST | Bulk-add watchlist entries |
/watchlists/:watchlistId/entries/:entryId | DELETE | Delete a watchlist entry |
KYC
| Endpoint | Methods | Description |
|---|---|---|
/kyc/applications | GET, POST | List or submit KYC applications |
/kyc/applications/:id | GET, PATCH | Get or update an application |
/kyc/applications/:id/verify-bvn | POST | Verify BVN (Bank Verification Number) |
/kyc/applications/:id/verify-nin | POST | Verify NIN (National Identification Number) |
/kyc/applications/:id/biometric-verify | POST | Combined biometric verification (one selfie, one call) |
/kyc/applications/:id/face-match | POST | Face match against BVN registry photo |
/kyc/applications/:id/liveness-check | POST | Run a liveness check |
/kyc/applications/:id/tier-requirements | GET | Requirements for the next KYC tier |
/kyc/applications/:id/upgrade-tier | POST | Upgrade an application’s KYC tier |
/kyc/applications/:id/risk-history | GET | Risk score history for an application |
/kyc/risk-changes | GET | Risk changes across applications |
/kyc/applications/:id/documents | GET, POST | Upload or list documents |
/kyc/applications/:id/documents/:docId/download | GET | Get presigned download URL |
/kyc/applications/:id/documents/:docId | DELETE | Delete document |
/kyc/applications/:id/approve | PATCH | Approve application |
/kyc/applications/:id/reject | PATCH | Reject application |
/kyc/providers/config | GET, PATCH | Get or update KYC provider config |
/kyc/providers/health | GET | KYC provider health status |
/kyc/providers/circuit-breakers | GET | Provider circuit breaker states |
KYB
| Endpoint | Methods | Description |
|---|---|---|
/kyc/kyb/applications | GET, POST | List or submit KYB applications |
/kyc/kyb/applications/:id | GET, PATCH | Get or update KYB application |
/kyc/kyb/applications/:id/verify-cac | POST | Verify CAC registration (RC number) |
/kyc/kyb/applications/:id/verify-directors | POST | Verify all directors via KYC |
/kyc/kyb/applications/:id/screen-beneficial-owners | POST | Screen BOs against sanctions |
/kyc/kyb/applications/:id/run-screening | POST | Run full KYB screening |
/kyc/kyb/applications/:id/documents | GET, POST | Upload or list KYB documents |
/kyc/kyb/applications/:id/documents/:docId/download | GET | Get presigned download URL |
/kyc/kyb/applications/:id/documents/:docId | DELETE | Delete KYB document |
/kyc/kyb/applications/:id/approve | PATCH | Approve KYB application |
/kyc/kyb/applications/:id/reject | PATCH | Reject KYB application |
Lookup
| Endpoint | Methods | Description |
|---|---|---|
/lookup/bvn | POST | Direct BVN lookup |
/lookup/nin | POST | Direct NIN lookup |
/lookup/cac | POST | Direct CAC lookup |
/lookup/history | GET | Direct-lookup history (saved customer profiles) |
/lookup/customers/:id | GET | Get a saved customer profile |
/lookup/customers/:id/create-application | POST | Start a KYC application from a lookup profile |
/lookup/customers/:id/create-kyb-application | POST | Start a KYB application from a CAC lookup profile |
Customers
| Endpoint | Methods | Description |
|---|---|---|
/customers/search | GET | Search customers by account number or name |
/customers/:hash/360 | GET | Unified customer 360 view |
Profiles
| Endpoint | Methods | Description |
|---|---|---|
/profiles/score | POST | Customer behavior score (JWT or API key) |
/profiles/transaction/:transactionId | GET | Behavior profile for a transaction sender |
Network
| Endpoint | Methods | Description |
|---|---|---|
/network/transaction/:transactionId | GET | Counterparty network for a transaction |
Reports
| Endpoint | Methods | Description |
|---|---|---|
/reports/sar | POST | Generate a SAR (Suspicious Activity Report) |
/reports/ctr | POST | Generate a CTR (Currency Transaction Report) |
/reports/ftr | POST | Generate an FTR |
/reports/mi | POST | Generate a management information report |
/reports/governance | POST | Generate a governance report |
/reports | GET | List reports |
/reports/:id | GET | Get report details |
/reports/:id/xml | GET | Download report as goAML XML |
/reports/:id/pdf | GET | Download report as PDF |
/reports/:id/xlsx | GET | Download report as Excel (.xlsx) |
/reports/:id/approve | PATCH | Approve report |
/reports/:id/file | PATCH | Mark report as filed |
NFIU
| Endpoint | Methods | Description |
|---|---|---|
/reports/:reportId/nfiu-filing | GET | Get NFIU filing status |
/reports/:reportId/nfiu-filing/retry | POST | Retry a failed NFIU filing |
Interdiction
| Endpoint | Methods | Description |
|---|---|---|
/interdictions | GET | Tenant interdiction queue (paginated) |
/interdictions/:actionId/execute | POST | Execute a PENDING interdiction action |
/interdictions/:actionId/retry | POST | Retry a FAILED interdiction action |
Dashboard
| Endpoint | Methods | Description |
|---|---|---|
/dashboard/summary | GET | Dashboard summary metrics |
Compliance
| Endpoint | Methods | Description |
|---|---|---|
/compliance/cbn | GET | CBN standards map with live evidence |
/compliance/health | GET | Tenant AML setup health score |
Countries
| Endpoint | Methods | Description |
|---|---|---|
/countries | GET | List countries (active only unless ?all=true) |
Tenant Configuration
| Endpoint | Methods | Description |
|---|---|---|
/tenants/me/alert-preferences | GET, PATCH | Get or update alert preferences |
/tenants/me/branding | PATCH | Update tenant branding |
/tenants/me/logo | POST | Upload tenant logo |
/tenants/me/kyc-config | PATCH | Update KYC configuration |
/tenants/me/nfiu-config | PATCH | Update NFIU filing configuration |
/tenants/me/interdiction-config | PATCH | Update interdiction configuration |
/tenants/me/case-escalation | PATCH | Update case escalation settings |
/tenants/me/periodic-review | PATCH | Update periodic review settings |
/tenants/me/retention | PATCH | Update data retention settings |
/tenants/me/fraud-channels | GET, PATCH | Get or update fraud channels |
/tenants/me/fx-rates | PATCH | Update FX rates |
/tenants/me/webhooks | PATCH | Configure outbound webhook endpoint |
Billing
| Endpoint | Methods | Description |
|---|---|---|
/billing/my-plan | GET | Get my subscription |
/billing/wallet | GET | Get wallet balance |
/billing/wallet/top-up-requests | GET, POST | List or create wallet top-up requests |
/billing/invoices | GET | List invoices |
/billing/invoices/:id/pay | POST | Pay an invoice |
/billing/usage | GET | Get usage summary |
/billing/verification-prices | GET | List per-check-type verification prices |
Audit
| Endpoint | Methods | Description |
|---|---|---|
/audit/events | GET | Query audit logs |
/audit/verify | GET | Verify audit chain integrity |
Engines
| Endpoint | Methods | Description |
|---|---|---|
/engines/health | GET | Engine health status |
/engines/config/:engine | GET, PATCH | Get or update engine configuration |
AI Assist
| Endpoint | Methods | Description |
|---|---|---|
/ai/cases/:id/summary | POST | AI-drafted case investigation summary |
/ai/sar-narrative | POST | AI-drafted SAR narrative (goAML) |
Media
| Endpoint | Methods | Description |
|---|---|---|
/media/logos/:tenantId/:filename | GET | Stream a tenant logo (public branding asset) |
System
| Endpoint | Methods | Description |
|---|---|---|
/health | GET | Health check (no auth required) |
HTTP Status Codes
| Code | Meaning | When It Happens |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
204 | No Content | Resource deleted or deactivated |
400 | Bad Request | Validation error — check request body |
401 | Unauthorized | Missing or invalid session/API key |
403 | Forbidden | Insufficient permissions for this action |
404 | Not Found | Resource does not exist |
409 | Conflict | Duplicate or conflicting state |
429 | Too Many Requests | Rate limit exceeded |
500 | Server Error | Unexpected error — retry with backoff |
Verifow — Enterprise-grade AML/CFT compliance for African financial institutions.