Screening

Alpha

Run fraud and compliance checks against an entity and get a rolled-up advisory assessment.

Base path: /v1

Purpose

Screening is the workhorse of Customer Intelligence. Each call runs independent check modules and returns fresh `check_runs` plus one advisory `assessment`. Synchronous today; webhooks planned for async results and continuous monitoring.

Usage

Call at signup, before first payout, or on step-up review. Empty body runs all fast checks; pass `types` to run a subset. Re-check whenever it matters. Each call is a new snapshot and history accrues.

Common Workflow

1Ensure the entity is registered and has identifiers for the checks you need.
2`POST /entities/{entity_id}/check` with `{}` or `{"types": ["sanctions", "velocity"]}`
3Inspect `assessment.risk_level`, `recommended_action`, and `reason_codes`.
4Drill into `check_runs[]` for per-signal detail and `signals{}` payloads.

Reason Codes

The vocabulary behind every verdict. Risk-bearing codes carry documented weights; `*_OK` and `*_CLEAR` codes carry zero.

Check type	Codes
`sanctions`	SANCTIONS_MATCH · SANCTIONS_CLEAR
`email_reputation`	EMAIL_DISPOSABLE · EMAIL_INVALID · EMAIL_OK
`phone`	PHONE_VOIP · PHONE_INVALID · PHONE_OK
`behavior`	AUTOMATION_SUSPECTED · FORM_FILLED_TOO_FAST · BEHAVIOR_OK
`velocity`	VELOCITY_DEVICE_REUSE · VELOCITY_WALLET_REUSE · VELOCITY_EMAIL_REUSE · VELOCITY_LINKED_TO_FLAGGED
`wallet_sanctions`	WALLET_SANCTIONS_HIT
`ip`	IP_TOR · IP_PROXY · IP_DATACENTER · IP_ADDRESS_GEO_MISMATCH

Integration Notes

Available now: `sanctions`, `email_reputation`, `phone`, `behavior`, `velocity`.
In rollout: `device`, `ip`, `wallet_sanctions`.
On the roadmap: `identity_match`, `wallet_risk`, `email_footprint`, `proxy_advanced`, `adverse_media`.
Unknown `types` values are rejected with `422`.
`SANCTIONS_MATCH` overrides the numeric score to `high`/`critical` + `review`.
Each risk-bearing code carries a documented weight; `*_OK` / `*_CLEAR` codes carry weight 0.

API Reference

POST/v1/entities/{entity_id}/check

Run Checks

Screen an entity and return check runs plus assessment.

Runs selected check modules and rolls them into one advisory assessment. Empty body or omitted `types` runs all fast checks. Each check returns its own `check_run` with `status`, `reason_codes`, and `signals` detail.

Parameters

Name	Type	Required	Description
`entity_id`	string	Required	Entity to screen.e.g. 9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e
`types`	string[]	Optional	Check types to run. Omit or `[]` for all fast checks.e.g. ["sanctions","email_reputation","phone","velocity"]

Request body

Schema

{}

Examples

Sample input

{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  },
  "body": {}
}

Sample output

{
  "request_id": "req_f6g7h8",
  "check_runs": [
    {
      "object": "check_run",
      "id": "cr_01",
      "check_type": "sanctions",
      "status": "completed",
      "reason_codes": [
        "SANCTIONS_CLEAR"
      ],
      "module_score": 0,
      "latency_ms": 34,
      "signals": {
        "match": false
      }
    },
    {
      "object": "check_run",
      "id": "cr_02",
      "check_type": "email_reputation",
      "status": "completed",
      "reason_codes": [
        "EMAIL_DISPOSABLE"
      ],
      "module_score": 0.45,
      "latency_ms": 12,
      "signals": {
        "disposable": true,
        "domain": "mailinator.com"
      }
    },
    {
      "object": "check_run",
      "id": "cr_03",
      "check_type": "phone",
      "status": "completed",
      "reason_codes": [
        "PHONE_VOIP"
      ],
      "module_score": 0.35,
      "latency_ms": 18,
      "signals": {
        "line_type": "voip",
        "region": "US"
      }
    },
    {
      "object": "check_run",
      "id": "cr_04",
      "check_type": "velocity",
      "status": "completed",
      "reason_codes": [
        "VELOCITY_DEVICE_REUSE"
      ],
      "module_score": 0.5,
      "latency_ms": 22,
      "signals": {
        "device_id_reuse_count": 5,
        "window_days": 90
      }
    }
  ],
  "assessment": {
    "object": "assessment",
    "id": "as_01",
    "score": 0.72,
    "risk_level": "medium",
    "recommended_action": "review",
    "reason_codes": [
      "EMAIL_DISPOSABLE",
      "PHONE_VOIP",
      "VELOCITY_DEVICE_REUSE"
    ],
    "check_run_ids": [
      "cr_01",
      "cr_02",
      "cr_03",
      "cr_04"
    ],
    "created_at": "2026-07-01T08:15:00Z"
  }
}

LLM markdown preview

### Run Checks

Screen an entity and return check runs plus assessment.

Use `POST /v1/entities/{entity_id}/check` to screen an entity and return check runs plus assessment.

Runs selected check modules and rolls them into one advisory assessment. Empty body or omitted `types` runs all fast checks. Each check returns its own `check_run` with `status`, `reason_codes`, and `signals` detail.

Required parameters:
- `entity_id`: string (example: `"9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"`). Entity to screen.

Optional parameters:
- `types`: string[] (example: `["sanctions","email_reputation","phone","velocity"]`). Check types to run. Omit or `[]` for all fast checks.

Example request:

```json
{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  },
  "body": {}
}
```

Example response:

```json
{
  "request_id": "req_f6g7h8",
  "check_runs": [
    {
      "object": "check_run",
      "id": "cr_01",
      "check_type": "sanctions",
      "status": "completed",
      "reason_codes": [
        "SANCTIONS_CLEAR"
      ],
      "module_score": 0,
      "latency_ms": 34,
      "signals": {
        "match": false
      }
    },
    {
      "object": "check_run",
      "id": "cr_02",
      "check_type": "email_reputation",
      "status": "completed",
      "reason_codes": [
        "EMAIL_DISPOSABLE"
      ],
      "module_score": 0.45,
      "latency_ms": 12,
      "signals": {
        "disposable": true,
        "domain": "mailinator.com"
      }
    },
    {
      "object": "check_run",
      "id": "cr_03",
      "check_type": "phone",
      "status": "completed",
      "reason_codes": [
        "PHONE_VOIP"
      ],
      "module_score": 0.35,
      "latency_ms": 18,
      "signals": {
        "line_type": "voip",
        "region": "US"
      }
    },
    {
      "object": "check_run",
      "id": "cr_04",
      "check_type": "velocity",
      "status": "completed",
      "reason_codes": [
        "VELOCITY_DEVICE_REUSE"
      ],
      "module_score": 0.5,
      "latency_ms": 22,
      "signals": {
        "device_id_reuse_count": 5,
        "window_days": 90
      }
    }
  ],
  "assessment": {
    "object": "assessment",
    "id": "as_01",
    "score": 0.72,
    "risk_level": "medium",
    "recommended_action": "review",
    "reason_codes": [
      "EMAIL_DISPOSABLE",
      "PHONE_VOIP",
      "VELOCITY_DEVICE_REUSE"
    ],
    "check_run_ids": [
      "cr_01",
      "cr_02",
      "cr_03",
      "cr_04"
    ],
    "created_at": "2026-07-01T08:15:00Z"
  }
}
```