Screening Flow

A screening takes subject data, matches it against global watchlists, scores the risk, and returns an automated decision.

Screening Lifecycle

                    ┌──────────┐
                    │ PENDING  │
                    └────┬─────┘
                         │
                    ┌────▼──────────┐
                    │ IN_PROGRESS   │
                    └────┬──────────┘
                         │
              ┌──────────┼──────────┐
              │                     │
        ┌─────▼─────┐        ┌─────▼────┐
        │ COMPLETED │        │  FAILED  │
        └─────┬─────┘        └──────────┘
              │
    ┌─────────┼──────────┬──────────────────┐
    │         │          │                  │
┌───▼───┐ ┌──▼────────┐ ┌▼──────────────┐ ┌▼──────┐
│APPROVE│ │APPROVE w/ │ │REVIEW_REQUIRED│ │ BLOCK │
│       │ │MONITORING │ │               │ │       │
└───────┘ └───────────┘ └───────────────┘ └───────┘

Screening Modes

Synchronous (SYNC)

The API processes the screening and returns the result in the same request (30-second timeout).

curl -X POST https://api.korastratum.com/api/v1/screenings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "SYNC",
    "purpose": "ONBOARDING",
    "subject": {
      "type": "INDIVIDUAL",
      "name": "Jane Smith",
      "date_of_birth": "1985-03-20",
      "nationality": "GB"
    },
    "checks": ["SANCTIONS", "PEP"]
  }'

Asynchronous (ASYNC)

The API returns a screening_id immediately (HTTP 202). Results are delivered via webhook.

curl -X POST https://api.korastratum.com/api/v1/screenings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ASYNC",
    "purpose": "ONBOARDING",
    "callback_url": "https://your-server.com/webhooks/screening",
    "subject": {
      "type": "INDIVIDUAL",
      "name": "Jane Smith",
      "date_of_birth": "1985-03-20",
      "nationality": "GB"
    },
    "checks": ["SANCTIONS", "PEP", "ADVERSE_MEDIA"]
  }'

Response (HTTP 202):

{
  "screening_id": "scr_abc123",
  "status": "PENDING"
}

Poll the result or wait for the webhook:

curl https://api.korastratum.com/api/v1/screenings/scr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Screening Purpose

The purpose field tells the engine why you're screening, which affects risk factor weighting:

Purpose	When to Use
ONBOARDING	New customer sign-up
PROFILE_CHANGE	Customer data changed (name, address, nationality)
TRANSACTION	Transaction-triggered screening
PERIODIC	Scheduled rescreen (e.g., quarterly)
BATCH	Bulk rescreen of your customer base
ON_DEMAND	Manual ad-hoc screening

What Gets Checked

Each screening runs the subject against multiple engines in parallel:

Check	Engine	Sources	Description
SANCTIONS	Sanctions Engine	9 lists (OFAC, UN, EU, UK, AU, CA, CH, JP)	Sanctions list matching
PEP	PEP Engine	4 lists (Global, Wikidata, African, Nigeria)	Politically Exposed Person screening
ADVERSE_MEDIA	Media Engine	News APIs, web feeds	Adverse media mentions

Matching Process

For each check, the engine:

1. Normalizes the subject name — lowercase, remove diacritics, strip titles (Mr., Dr., etc.)
2. Compares against all entries using a composite algorithm:
   • Jaro-Winkler distance (60% weight) — handles typos and transpositions
   • Token matching (15%) — handles name reordering ("John Doe" ↔ "Doe John")
   • N-gram similarity (15%) — catches character-level variations
   • Soundex phonetic (10%) — catches names that sound alike
3. Classifies match strength:
   • EXACT — normalized exact match
   • STRONG — composite score ≥ 0.92
   • POSSIBLE — composite score ≥ 0.75

See Matching Algorithms for full details.

Risk Scoring

After matching, the risk engine calculates a composite score from 0 to 1000:

Risk Band	Score Range	Typical Decision
LOW	0–250	APPROVE
MEDIUM	251–500	APPROVE_WITH_MONITORING
HIGH	501–750	REVIEW_REQUIRED
CRITICAL	751–1000	BLOCK

Risk factors that contribute to the score:

• Sanctions match — High impact (weight: 0.8)
• PEP match — High impact (weight: 0.7)
• Adverse media — Medium impact (weight: 0.5)
• High-risk country — Medium impact (FATF blacklist/greylist, EU high-risk)
• Customer type — Individual vs entity
• Transaction patterns — Velocity and amount thresholds

See Risk Scoring for the full scoring methodology.

Decision Outcomes

Outcome	Meaning	Recommended Action
APPROVE	No significant risk	Proceed with onboarding/transaction
APPROVE_WITH_MONITORING	Low risk with flags	Proceed but set up ongoing monitoring
REVIEW_REQUIRED	Potential matches found	Route to compliance team for manual review
BLOCK	High-confidence match	Deny and file regulatory report if required

Subject Types

Type	Fields	Example
INDIVIDUAL	name, date_of_birth, nationality, identifiers	A person
ENTITY	name, country, registration_number	A company or organization

Supported identifier types:

Type	Description
PASSPORT	Passport number
NATIONAL_ID	National ID card
DRIVERS_LICENSE	Driver's license
BVN	Bank Verification Number (Nigeria)
NIN	National Identification Number
TIN	Tax Identification Number
BUSINESS_REG	Business registration number
LEI	Legal Entity Identifier

Next Steps

• Server Integration — Build a complete backend integration
• Batch Screening — Screen multiple subjects at once
• Case Management — Handle REVIEW_REQUIRED decisions
• Webhooks — Real-time event delivery