WhoComply Integration Guide
WhoComply is the customer compliance system of record for your institution. Your systems push raw data in, your compliance team works inside the WhoComply dashboard, and your operational systems read state and receive webhook notifications. This guide covers the API surface your engineering team needs.
How integration works
Your engineering responsibility ends at sending raw data and reacting to operational hooks. WhoComply owns the resulting compliance state — the unified customer risk view, alerts, cases, reports, and the audit trail an examiner reads.
Inbound — what you push into WhoComply
| Surface | Endpoint | Used for |
|---|---|---|
| Customer profiles | POST /customers | When onboarding happens or KYC details change |
| Transaction + onboarding events | POST /events/webhook | Every event that should drive scoring; runs the enrichment pipeline immediately |
| Native ledger postings | POST /postings | Recording funds movements directly in WhoComply (double-entry, hash-chained, signed) |
| Monitoring rules + watchlist entries | POST /monitoring-rules, POST /watchlist-entries | Configuring the native engines |
The first three are the data ingestion paths you'll use most. They're independent — most institutions use all three, some use only the events webhook plus customer pushes when their core banking is the system of record for funds.
Provider activation (Sumsub, ComplyAdvantage, etc.) is a dashboard action handled by your compliance admin, not an API call. See Integrations.
Outbound — what WhoComply sends back
| Surface | Endpoint | Used for |
|---|---|---|
| Webhook subscriptions | POST /webhooks | Registering endpoints to receive alert.created, alert.resolved, alert.dismissed events |
| Risk view reads | GET /customers/{id}/risk-view | Transaction-time decisioning: rating, composite score, sanctions flag, EDD requirement |
| Customer state reads | GET /customers/{id} | Operational checks against current KYC and risk state |
You don't store WhoComply's risk view in your own database. Hit risk-view at decision time to read the authoritative state.
Where compliance work happens
Triage, case management, report filing, and provider activation all happen inside the WhoComply dashboard. Your engineering team does not need to build a parallel UI.
Authentication
All integration endpoints use API keys. Include your key in the Authorization header:
curl https://api.whocomply.com/api/v1/tenants/your-org/customers \
-H "Authorization: Bearer wc_0aa39ad26ab1.95ed0c0f859a..."
API keys are created by your admin in the dashboard. Each key has explicit scoped permissions set at creation time.
Base URL
https://api.whocomply.com/api/v1
Most resource endpoints are tenant-scoped:
https://api.whocomply.com/api/v1/tenants/{your-slug}/customers
The events webhook is the one exception — it lives at the unscoped path because the body carries tenant_id:
POST https://api.whocomply.com/api/v1/events/webhook
Your tenant slug and tenant ID are provided during onboarding.
Response Format
Success
{
"status": "ok",
"data": { ... }
}
Error
{
"status": "error",
"message": "human-readable description"
}
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
204 | Deleted, no body |
400 | Bad request |
401 | Invalid or missing API key |
403 | Valid key, wrong tenant, or insufficient scope |
404 | Not found |
500 | Server error |
Errors
Error responses include a message field. Use it in your error handling:
{
"status": "error",
"message": "email is required"
}
Pagination uses limit (default 20, max 100) and offset (default 0) query parameters on all list endpoints.