Integrations

Your institution probably already pays for KYC, screening, or transaction-monitoring providers. WhoComply does not ask you to rip those out. Your compliance admin activates each provider in the dashboard, and WhoComply orchestrates their signals into one customer risk view alongside our native engines.

This page is for the engineering team integrating with WhoComply. Activating providers is done by your compliance admin in the dashboard, not via API. What follows describes what changes for your integration once a provider is active.

Why integrations exist

A typical Nigerian fintech runs:

• Sumsub or Smile ID for individual KYC
• ComplyAdvantage or similar for sanctions / PEP / adverse-media screening
• Sumsub KYT or another tool for transaction monitoring of crypto / cross-border flows

Each of those produces compliance signals — a verified applicant, a sanctions hit, a flagged transaction — but they live in three separate dashboards. The CBN circular (BSD/DIR/PUB/LAB/019/002) requires institutions to produce a unified customer risk view that an examiner can audit. WhoComply is the layer where those signals collide.

The mechanism is plugins. Each plugin is a per-tenant adapter for one provider. When the compliance admin activates the Sumsub plugin, WhoComply starts reading the institution's Sumsub KYC review state, ingesting their applicant webhooks, and surfacing every signal as an alert, an audit event, or a customer-record update.

Three deployment modes

For each pipeline stage (KYC, Screening, Monitoring), the compliance admin chooses one of three modes:

Native

WhoComply's built-in engine runs the stage. No third-party provider involved. This is the default until a plugin is activated.

Plugin (synchronous)

Every event flows through a provider plugin synchronously during the pipeline. Example: routing the Screening stage to ComplyAdvantage means each customer event triggers a fresh POST /searches against ComplyAdvantage's live watchlists, with the matches surfaced inline.

External (provider-authored)

The stage is skipped in the synchronous pipeline. The provider runs the work in the background and posts alerts back to WhoComply via webhook. Used when a provider does ongoing monitoring (e.g. Sumsub's continuous applicant review, ComplyAdvantage's monitored search updates) rather than offering a synchronous "screen this customer right now" call.

Each mode is set per-stage. A tenant can mix modes — KYC via plugin Sumsub, Screening via plugin ComplyAdvantage, Monitoring native — without any code change on your side.

What changes for your integration

You keep doing the same things you always do:

• POST customer profiles to /customers
• POST transactions / events to /postings or to the orchestrator events endpoint
• Read back risk views via /customers/{id}/risk-view
• Receive webhooks at the endpoints you registered with /webhooks

What changes is the data inside those responses and webhooks gets richer:

Risk views become multi-source

Before: a customer's risk_view reflected WhoComply's native screening + scoring.

After a plugin is activated: the same risk_view includes signals from the activated provider. A PEP hit pulled by ComplyAdvantage shows up alongside any native watchlist matches. A KYC rejection from Sumsub shows up as kyc_status: rejected with kyc_provider: sumsub on the customer record.

You don't have to do anything to consume the merged view; just keep reading the same endpoints.

Webhook payloads carry provenance

Every alert WhoComply emits carries metadata identifying the source:

{
  "alert_id": "...",
  "severity": "critical",
  "title": "Sumsub KYC rejected: SANCTIONS, PEP",
  "metadata": {
    "source": "plugin",
    "plugin": "sumsub",
    "event_source": "sumsub:applicantReviewed",
    "reject_labels": ["SANCTIONS", "PEP"],
    "reject_type": "FINAL"
  }
}

Your downstream systems can branch on metadata.plugin if they want to handle provider-attributable alerts differently (e.g. auto-acknowledge false-positives from one provider, escalate everything from another).

Customer KYC state may flip from outside your system

When a provider plugin pushes a KYC state change (Sumsub's reviewer rejects an applicant, for example), WhoComply updates the customer's kyc_status, audit-logs it as kyc.rejected, and re-runs the risk-scoring pipeline. The next time you call /customers/{id} or /customers/{id}/risk-view, you'll see the new status. If you've subscribed to the matching webhook event, you'll receive a delivery in real time.

This is by design: a regulator-defensible compliance system cannot have a customer's KYC state lag behind what the provider's reviewer just decided.

Customer linkage to providers uses kyc_provider_ref

When you create a customer who has already been onboarded through one of your providers, include their provider-side identifier:

{
  "external_id": "your-internal-id",
  "customer_type": "individual",
  "full_name": "Adebayo Mustapha",
  "email": "adebayo@example.com",
  "kyc_provider": "sumsub",
  "kyc_provider_ref": "5d2b1a3e0000000000000001"
}

WhoComply uses this reference to correlate provider webhooks back to your customer record. If the field is empty, the orchestrator falls back to matching on account_refs.

Available providers

The set of plugins compiled into your WhoComply build appears under Integrations in the dashboard. Current production plugins:

More providers are being added; plugin activation never requires an integration change on your side.

Common questions

Do I need different API keys when a plugin is activated?

No. Your existing API keys keep working. Plugins affect what signals flow through the platform, not how you authenticate to it.

Can I see which provider produced a particular alert or screening hit?

Yes. Every alert's metadata.plugin field identifies the source plugin (when one is involved). Screening hits include the originating list source; webhook deliveries carry the same provenance.

What if my institution doesn't use any of the listed providers?

Your tenant runs in all-native mode by default. The pipeline uses WhoComply's built-in screening watchlist and monitoring rules engine. You integrate the same way; the orchestration layer simply has fewer sources to merge.

When a plugin is deactivated, what happens to historical alerts and audit events?

Nothing. Audit events and alerts are immutable. Deactivating a plugin only stops new signals from flowing in; the historical record carries its provenance forever.

Can I trigger the pipeline myself if I know a customer's state changed?

Yes. POST an onboarding-type event with the customer's ID to your orchestrator endpoint, and the pipeline will re-run scoring. Your compliance admin can also do this from the dashboard's customer detail page.