Customer Intelligence
AlphaKnow who you're onboarding. Send us what you know about a user and get back a clear, explainable risk verdict backed by fraud and compliance signals.
Base path: /v1
Purpose
Customer Intelligence is the product surface for onboarding risk. You integrate once against a stable contract: register an entity, run checks when it matters, and receive an advisory assessment with transparent reason codes. No black box, and you keep the final decision.
Usage
Wire this into signup and onboarding: register early (even pre-form, with just a device or IP), screen at signup, first payout, or step-up review. Each `/check` is a fresh snapshot; history accrues. Signals only get richer over time as new check types roll out.
Unlocking This Service
Send `Authorization: Bearer <token>` or `X-Service-Token` on every `/v1` call. Generate credentials in the Falador dashboard with `entities:write` and `checks:run` scopes.
Common Workflow
- 1Register the entity with `POST /v1/entities`. Idempotent on your `reference_id` and safe to retry with the same `Idempotency-Key`.
- 2Screen when ready with `POST /v1/entities/{entity_id}/check`. An empty body runs every fast check.
- 3Read the assessment: `risk_level`, `recommended_action`, and `reason_codes` in the response.
- 4Re-POST with the same `reference_id` or `PATCH` the entity as you learn new identifiers. The next check picks them up.
Conventions
- Auth: `Authorization: Bearer <token>` or `X-Service-Token` on every `/v1` call.
- Idempotency: `POST /v1/entities` requires `Idempotency-Key`; same key + same body replays the stored response. Same key + different body returns `409`.
- Request tracing: every response carries `request_id`, echoed as `X-Request-Id`.
- Self-describing objects: every object has an `object` field (`entity`, `identifier`, `check_run`, `assessment`) and an `id`.
- Errors: uniform envelope: `{"error": {"type", "code", "message", "request_id"}}`.
Check Types
Every signal is atomic. The cluster is what matters. Velocity sees identifier reuse across programs, the kind of signal a single-user check cannot produce.
| Check type | Needs | Tells you | Status |
|---|---|---|---|
sanctions | name (+ optional DOB/country) | Is this person on a sanctions or watchlist? | Live |
email_reputation | Disposable / throwaway domain, invalid address. | Live | |
phone | phone | Valid?, region, line type (mobile / landline / VoIP). | Live |
behavior | on-page signals | Automation / bot signup (filled too fast, pasted everything). | Live |
velocity ★ | device / wallet / email | Shared Fraud Map: how many other accounts across the network share this identifier. Cross-program reuse no single-user check can see. | Live |
device | device fingerprint | New device?, emulator, spoofing. | Rollout |
ip | IP | Proxy / VPN / Tor / datacenter, geo mismatch. | Rollout |
wallet_sanctions | wallet address | Is the wallet on a sanctions list? | Rollout |
Response Objects
| Object | Key fields |
|---|---|
entity | `id`, `entity_type` (individual|business|wallet), `reference_id`, `display_name`, `status` (active|archived), `metadata`, `created_at`, `updated_at` |
identifier | `id`, `id_type` (email, phone, device_id, wallet_address, …), `value_raw`, `status` (active|detached) |
check_run | `check_type`, `status` (completed|degraded|error|timeout|skipped), `reason_codes[]`, `signals{}`, `module_score`, `latency_ms` |
assessment | `score`, `risk_level` (low|medium|high|critical), `recommended_action` (approve|review), `reason_codes[]`, `check_run_ids[]` |
Reading the Verdict
The assessment rolls every signal into one advisory result. A clean user returns `low` / `approve`. Reason codes are per-check all-clears (e.g. `SANCTIONS_CLEAR`, `EMAIL_OK`) which carry zero weight, so the score stays at `0`.
- risk_level
- Banded read of the score: `low` · `medium` · `high` · `critical`.
- recommended_action
- Our suggestion: `approve` · `review` today (`decline` reserved for a future policy tier). You set the thresholds.
- reason_codes
- The exact signals that drove the verdict, for compliance review and audit.
- score
- Transparent weighted sum over reason codes. `*_OK` / `*_CLEAR` codes carry weight 0.
- Compliance never gets averaged away. `SANCTIONS_MATCH` forces `high`/`critical` + `review` regardless of everything else.
- A check never breaks your flow. Timeouts and missing inputs degrade to their own status; the call still returns `200`.
- Check types in rollout return a clear not-yet-enabled status, never a false all clear.
Integration Notes
- Nothing is required except a `reference_id`. Send more identifiers to unlock more checks.
- Run a subset: `{"types": ["sanctions", "velocity"]}`; omit `types` to run all fast checks.
- Accepted identifier types include `email`, `phone`, `device_id`, `ip`, `wallet_address`, `behavior`, `passport`, `national_id`, `dob`, `nationality`.
- New check types are additive. Opt in by name, never by re-integrating. Browse the Check Catalog service or `GET /v1/checks` (planned).
- See the Entities, Screening, and Check Catalog services below for endpoint-level reference.