WhoComply Horizontal Logo

Customers

Customers represent the individuals or businesses your institution serves. Each customer has a risk profile that is dynamically scored across six factors.

POST/tenants/{slug}/customers

Create customer

Push a customer when they onboard or update their KYC. Requires write scope.

  • Name
    email
    Type
    string
    Description

    Customer email. Must be unique within the tenant.

  • Name
    customer_type
    Type
    string
    Description

    individual or corporate.

  • Name
    full_name
    Type
    string
    Description

    Full name (for individuals).

  • Name
    business_name
    Type
    string
    Description

    Business name (for corporates).

  • Name
    external_id
    Type
    string
    Description

    Your internal customer reference.

  • Name
    nationality
    Type
    string
    Description

    ISO country code (e.g. NG).

  • Name
    phone
    Type
    string
    Description

    Phone number.

  • Name
    date_of_birth
    Type
    string
    Description

    ISO date (e.g. 1990-04-15).

  • Name
    occupation
    Type
    string
    Description

    Customer occupation.

  • Name
    source_of_funds
    Type
    string
    Description

    Declared source of funds.

  • Name
    pep_status
    Type
    string
    Description

    One of none, declared, screened, confirmed. Defaults to none.

  • Name
    kyc_status
    Type
    string
    Description

    Current KYC state if you already onboarded the customer through your provider. One of pending, in_review, approved, rejected, expired.

  • Name
    kyc_provider
    Type
    string
    Description

    Provider that performed KYC, e.g. sumsub. Used to correlate provider webhooks back to this customer record. See Integrations.

  • Name
    kyc_provider_ref
    Type
    string
    Description

    Provider-side identifier for this customer (e.g. Sumsub applicantId).

  • Name
    onboarding_channel
    Type
    string
    Description

    digital, agent, branch, referral, or partner.

  • Name
    account_refs
    Type
    string[]
    Description

    Array of account references linking this customer to your ledger / core banking.

  • Name
    address
    Type
    object
    Description

    Address sub-object: line1, line2, city, state, country, postal_code.

  • Name
    tags
    Type
    string[]
    Description

    Free-form tags for filtering.

The full request also accepts business_type, industry_type, registration_no, tax_id, income_range, source_of_wealth, beneficial_owners, related_parties, and metadata.

Request

POST
/tenants/{slug}/customers
curl -X POST "https://api.whocomply.com/api/v1/tenants/kuda-mfb/customers" \
  -H "Authorization: Bearer wc_..." \
  -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",
    "kyc_provider": "sumsub",
    "kyc_provider_ref": "5d2b1a3e0000000000000001",
    "account_refs": ["ACC-001"]
  }'

Response (201)

{
  "status": "ok",
  "data": {
    "id": "f1e2d3c4-...",
    "tenant_id": "...",
    "email": "adebayo@example.com",
    "customer_type": "individual",
    "full_name": "Adebayo Mustapha",
    "kyc_status": "pending",
    "kyc_provider": "sumsub",
    "kyc_provider_ref": "5d2b1a3e0000000000000001",
    "risk_rating": "medium",
    "account_refs": ["ACC-001"],
    "created_at": "2026-04-17T10:00:00Z"
  }
}
GET/tenants/{slug}/customers

List customers

Returns customers for the tenant. Requires read scope.

  • Name
    limit
    Type
    integer
    Description

    Number of results (1-100, default 20).

  • Name
    offset
    Type
    integer
    Description

    Pagination offset (default 0).

Request

GET
/tenants/{slug}/customers
curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/customers?limit=20&offset=0" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": [
    {
      "id": "f1e2d3c4-...",
      "full_name": "Adebayo Mustapha",
      "customer_type": "individual",
      "kyc_status": "pending",
      "risk_rating": "medium",
      "created_at": "2026-04-17T10:00:00Z"
    }
  ]
}
GET/tenants/{slug}/customers/{id}

Get customer

Returns a single customer by ID. Requires read scope.

Request

GET
/tenants/{slug}/customers/{id}
curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/customers/{customer_id}" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": {
    "id": "f1e2d3c4-...",
    "tenant_id": "...",
    "email": "adebayo@example.com",
    "customer_type": "individual",
    "full_name": "Adebayo Mustapha",
    "phone": "+2348012345678",
    "nationality": "NG",
    "kyc_status": "approved",
    "kyc_provider": "sumsub",
    "kyc_provider_ref": "5d2b1a3e0000000000000001",
    "risk_rating": "medium",
    "pep_status": "none",
    "onboarding_channel": "digital",
    "account_refs": ["ACC-001"],
    "created_at": "2026-04-17T10:00:00Z",
    "updated_at": "2026-04-17T10:00:00Z"
  }
}
GET/tenants/{slug}/customers/{id}/risk-view

Get risk view

Returns the unified risk view for a customer. Includes the customer profile, risk scores (composite + per-factor), identity verification status, active alerts, open cases, screening results, and compliance flags. Requires read scope.

When provider plugins are activated for the tenant, the risk view merges signals from those providers (e.g. ComplyAdvantage screening hits, Sumsub KYC state) alongside WhoComply's native engines. You consume the merged view; no per-provider branching needed in your code.

Response fields

  • Name
    customer
    Type
    object
    Description

    Full customer profile.

  • Name
    risk
    Type
    object
    Description

    Risk scores: composite_score (0-1000), plus per-factor scores identity_score, geographic_score, product_score, behavioral_score, channel_score, relationship_score.

  • Name
    active_alerts
    Type
    array
    Description

    Currently open alerts for this customer.

  • Name
    open_cases
    Type
    array
    Description

    Currently open investigation cases.

  • Name
    is_sanctioned
    Type
    boolean
    Description

    Whether the customer has confirmed sanctions hits.

  • Name
    requires_edd
    Type
    boolean
    Description

    Whether enhanced due diligence is required.

Request

GET
/tenants/{slug}/customers/{id}/risk-view
curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/customers/{id}/risk-view" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": {
    "customer": { "id": "...", "full_name": "Adebayo Mustapha", "risk_rating": "medium" },
    "risk": {
      "composite_score": 320,
      "identity_score": 150,
      "geographic_score": 100,
      "product_score": 80,
      "behavioral_score": 200,
      "channel_score": 50,
      "relationship_score": 60
    },
    "active_alerts": [],
    "open_cases": [],
    "is_sanctioned": false,
    "requires_edd": false,
    "generated_at": "2026-04-17T10:05:00Z"
  }
}
GET/tenants/{slug}/customers/{id}/risk-history

Get risk history

Returns the immutable risk-rating history for a customer: every transition with the reason, trigger type, composite score, and actor. CBN §5.4 requires this audit trail.

Request

GET
/tenants/{slug}/customers/{id}/risk-history
curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/customers/{id}/risk-history" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": [
    {
      "rating_from": "medium",
      "rating_to": "high",
      "reason": "Sumsub review returned RED",
      "trigger_type": "onboarding",
      "score": 580,
      "actor_type": "system",
      "created_at": "2026-04-17T10:08:00Z"
    }
  ]
}

Was this page helpful?