Quick Start

Push your first customer, fire your first transaction event, read the resulting risk state, and register a webhook for operational notifications.

Prerequisites

You need three things from your WhoComply admin:

An API key (starts with wc_)
Your tenant slug (e.g. kuda-mfb)
Your tenant ID (UUID) — used by the events webhook

API_KEY="wc_0aa39ad26ab1.95ed0c0f859a8cb2..."
SLUG="kuda-mfb"
TENANT_ID="79e660ad-9532-4b1b-b94a-725c90e74f25"
BASE="https://api.whocomply.com/api/v1/tenants/$SLUG"

Push a customer

When a customer onboards in your system, push their profile so WhoComply can score them and attach all subsequent compliance state to them.

account_refs links this customer to one or more references in your core banking. WhoComply uses these to map incoming transaction events to customers.

Request

POST

/tenants/{slug}/customers

curl -X POST "$BASE/customers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "adebayo@example.com",
    "customer_type": "individual",
    "full_name": "Adebayo Mustapha",
    "nationality": "NG",
    "phone": "+2348012345678",
    "source_of_funds": "salary",
    "account_refs": ["ACC-001"]
  }'

Response (201)

{
  "status": "ok",
  "data": {
    "id": "f1e2d3c4-...",
    "email": "adebayo@example.com",
    "risk_rating": "medium",
    "kyc_status": "pending",
    "created_at": "2026-04-17T10:00:00Z"
  }
}

Event-driven ingestion is the canonical path. POST every transaction event to the orchestrator's /events/webhook route. The pipeline runs immediately: resolve customer, load risk profile, screen, monitor against your rules, score, persist alerts.

The events webhook lives at the unscoped path because the body carries tenant_id. account_ref must match one of the customer's account_refs so the resolver can map the event to the right profile.

Request

POST

/events/webhook

curl -X POST "https://api.whocomply.com/api/v1/events/webhook" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "'"$TENANT_ID"'",
    "event_type": "transaction",
    "payload": {
      "transaction_id": "TXN-2026-04-17-001",
      "account_ref": "ACC-001",
      "amount": 6500000,
      "currency": "NGN",
      "direction": "inbound",
      "description": "Salary credit",
      "reference": "TXN-2026-04-17-001"
    }
  }'

Response (202)

{
  "status": "accepted",
  "event_id": "evt-..."
}

If you'd rather have WhoComply record the funds movement directly (double-entry, hash-chained, signed), use the native ledger instead.

Read the risk view

At transaction time — when your core banking is deciding whether to release a payment, hold a withdrawal, or step up authentication — read the unified risk view directly.

Don't cache or mirror this in your own database. Read at decision time so you act on current state.

Request

GET

/tenants/{slug}/customers/{id}/risk-view

curl "$BASE/customers/{customer_id}/risk-view" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "status": "ok",
  "data": {
    "customer": { "id": "...", "risk_rating": "high" },
    "risk": {
      "composite_score": 580,
      "identity_score": 200,
      "behavioral_score": 220
    },
    "active_alerts": [{ "id": "...", "severity": "critical" }],
    "is_sanctioned": false,
    "requires_edd": true,
    "generated_at": "2026-04-17T10:05:00Z"
  }
}

Register a webhook

Get notified when WhoComply needs your operational systems to react — typically a new alert that warrants holding a wallet, blocking a transaction, or stepping up monitoring.

The signing_secret is shown once. Store it; you'll need it to verify webhook signatures.

Request

POST

/tenants/{slug}/webhooks

curl -X POST "$BASE/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Operational alert handler",
    "url": "https://your-app.com/webhooks/whocomply",
    "event_types": ["alert.created", "alert.resolved", "alert.dismissed"]
  }'

Response (201)

{
  "status": "ok",
  "data": {
    "endpoint": {
      "id": "wh-...",
      "label": "Operational alert handler",
      "url": "https://your-app.com/webhooks/whocomply",
      "event_types": ["alert.created", "alert.resolved", "alert.dismissed"],
      "status": "active"
    },
    "signing_secret": "whsec_557027b646f3fc3da8fed50e..."
  }
}