Documentation

Everything you need to go from first API call to regulator-ready filing. The engine is deterministic, the scores are inspectable, and nothing here is marketing.

Overview

Mizan AI is a compliance investigation workspace: it screens names, entities and transaction behaviour against sanctions, PEP and adverse-media watchlists; scores every subject on an inspectable 0–100 scale; and produces a complete, defensible case file — reasoning trace, timeline, disposition and regulator-ready export — for every alert.

Three layers, one file:

• Screen — normalise, match, score. Transliteration-aware and distinctiveness-guarded.
• Investigate — the agent assembles the dossier and writes the reasoning trace; a human disposes.
• Report — goAML-shaped XML, dossier PDF, immutable event log.

Mizan (ميزان) means "the balance". Every decision is weighed — and the weights are visible.

Quick start

Median time to first production screening is 48 hours. The fastest path:

1. Sign up for a free trial (full Growth capability, no card).
2. Generate an API key from the dashboard, or upload a CSV/SFTP batch in the workspace.
3. Map your fields: subject name, DOB, nationality, jurisdiction, transaction data.
4. Run your first screening and read the trace.

A minimal screening via the API — POST /v1/screen:

# Screen one subject against your full watchlist stack
curl https://api.mizan.ai/v1/screen \
  -H "Authorization: Bearer mk_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "name": "Mohammed Abdul Rahman Al Farsi",
      "dob": "1978-04-12",
      "nationality": "AE"
    },
    "context": { "case_ref": "TX-88213", "amount_usd": 84000 }
  }'

The response includes the composite score, every factor with its delta, the matching list entries, and the reasoning trace:

{
  "score": 87,
  "band": "CRITICAL",
  "factors": [
    { "label": "Name similarity",
      "detail": "0.94 fuzzy match, alias 'AL FARSI SALEM MOHAMMED'",
      "delta": 0 },
    { "label": "Date of birth",
      "detail": "Exact match — 1978-04-12",
      "delta": +8 }
  ],
  "trace": [ /* reasoning steps, plain language */ ]
}

Core concepts

• Subject — a person or entity being screened.
• Watchlist record — a list entry with name, aliases, DOB, nationality, type (PERSON/ENTITY) and source.
• Screening — one subject against your full list stack; produces one score and trace.
• Alert — a screening that crosses your review threshold, entering the queue.
• Case — the dossier for one alert: score, factors, timeline, trace, disposition.
• Disposition — the analyst's decision: close, request information, escalate to MLRO, file STR, freeze.

Name normalisation

Arabic-to-Latin transliteration is the single largest source of false negatives in Gulf-region screening. The same person appears as Mohammad, Mohammed, Muhammad, Muhammed, Mohamad, Mohamed, Mohd. Mizan canonicalises before comparing:

• Transliteration folding — spelling variants collapse to a canonical token (e.g. all of the above → MUHAMMAD; AHMED/AHMAD → AHMAD; YOUSEF/YUSUF → YUSUF).
• Diacritic stripping — precomposed mapping, no edge cases from Unicode normalisation.
• Corporate noise removal — "Falcon Trading LLC" and "Falcon Trading FZE" compare on the stem; suffixes that carry no identity signal are discarded (LLC, FZE, DMCC, LTD, SARL, GMBH…).
• Internal-descriptor filtering — cash tills, payroll files, card settlements and own-account transfers are booking metadata, not parties; they are filtered at ingestion.

Matching algorithms

Two complementary matchers run on every normalised pair, and the stronger result is taken:

• Jaro–Winkler — strong on transpositions and shared prefixes; how misspelled and transliterated names actually fail. Prefix boost capped at 4 characters, standard 0.1 factor.
• Token-set — handles reordering, missing middle names and extra tokens. "SALEM AL FARSI" vs "AL FARSI SALEM MOHAMMED" scores high; unmatched tokens dilute only mildly, because watchlists routinely hold fuller names than transaction records.

Distinctiveness guard. A high fuzzy score built only from generic vocabulary — "Delta Marine Supplies" vs "Meridian Shell Holdings" — is an artefact, not evidence. If no distinctive token (rare, identifying word) is shared, the score is suppressed by up to 30 points; if all distinctive tokens match, it is boosted. This single control removes an entire class of false positives.

Discriminators. Date of birth is the strongest available discriminator: an exact DOB adds +8; a mismatch subtracts up to −26. Nationality agreement adds +6, disagreement −12. These are weights, not guesses — each is itemised in the factor list.

Risk model & bands

The composite score is a transparent sum of factors, each with a documented delta:

Bands: CRITICAL ≥ 80 HIGH 60–79 MEDIUM 40–59 LOW 20–39 MINIMAL < 20. Thresholds are configurable per tenant; the auto-clear threshold defaults to < 25 and always retains the trace as the audit record.

Behavioural detection

Names are only half the story. Mizan screens transaction streams for patterns:

• Structuring below reporting threshold (e.g. repeated ≤ USD 9,999 transfers)
• Round-value bias
• Rapid pass-through of funds
• Counterparty concentration
• Dormancy followed by high-value activity
• Volume inconsistent with declared profile
• High-risk jurisdiction exposure

Each pattern is detected by an inspectable rule and appears in the trace as a named signal — never as a black-box "ML flag".

Investigation workflow

1. Queue. Alerts rank by composite risk, highest first. Band, score and name at a glance.
2. Dossier. Score dial, factor breakdown, entity profile, transaction timeline.
3. Run investigation. The agent reads the file, screens, reasons and recommends.
4. Disposition. Close (no suspicion) · Request information · Escalate to MLRO · File STR · Freeze funds and file STR. Every disposition is attributed to a named analyst with a timestamp.

Human-in-the-loop by design: the agent recommends and auto-clears only the lowest band; it never files autonomously.

Reasoning trace

The trace is the signature element — a plain-language record of every step the agent took, rendered as it runs:

mizan.agent INVESTIGATION_STARTED · 14 reasoning steps · engine v1.0
mizan.agent SCREENING_COMPLETED · 3 of 12 lists hit
mizan.agent RISK_SCORED · composite 78 → HIGH
mizan.agent POLICY_OVERRIDE · none applied
mizan.agent DISPOSITION_RECOMMENDED · escalate to MLRO
[ANALYST] PENDING_HUMAN_REVIEW · agent does not file autonomously

The trace doubles as the audit record and the first draft of the filing narrative — so the STR and the case file can never contradict each other.

MLRO console

The MLRO Console (Enterprise) shapes the workspace around the officer who signs: escalations, dual-control approvals, committee review flows, workflow rules, supervisory reporting and the audit log.

• Escalation queue — cases escalated by analysts arrive with reason, risk band, evidence and the regulatory clock.
• Dual control — STR filings, freeze orders and watchlist changes require two named approvers, enforced by the system.
• Committee flows — high-stakes cases route to a review committee; opinions and majority are recorded in the case file.
• Workflow rules — auto-clear thresholds, band boundaries and overrides, versioned and attributed.
• Supervisory reporting — STR volumes, timeliness, freeze orders and backlogs derived live from the case ledger.
• Audit log — every console decision appended to the immutable event log: actor, timestamp, reason.

Dual control is enforced by the system, not by office etiquette: an approval holds until the second named approver signs, and the evidence each approver signed against is attached.

An interactive demo of the console runs at mlro-console.html (sign in with the demo account).

Reporting & export

• goAML-shaped XML — STR/CTR reports with the filing narrative drafted from trace evidence, and the audit trail embedded as metadata.
• Dossier PDF — human-readable case file: dial, factors, timeline, trace, disposition.
• Event log JSON — the complete, immutable chain of who did what, when, and why.
• Custom templates — Enterprise tier supports any regulator format.

API reference

Base URL https://api.mizan.ai/v1. Authenticate with a bearer key (mk_live_…) from the dashboard.

Batch screening:

# Async batch — webhook fires when all subjects are scored
curl -X POST https://api.mizan.ai/v1/screen/batch \
  -H "Authorization: Bearer $MIZAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://your-bucket/customers.csv",
    "field_map": { "name": "full_name", "dob": "birth_date" },
    "webhook": "https://you.example.com/hooks/mizan"
  }'

SDKs

Python, Node.js and Go clients wrap the API with retries, typed models and trace streaming. Install from your package manager:

# pip install mizan-ai
from mizan import Mizan

client = Mizan(api_key="mk_live_…")
result = client.screen(
    name="Mohammed Abdul Rahman Al Farsi",
    dob="1978-04-12",
    nationality="AE",
)
print(result.score, result.band)
for step in result.trace:
    print("·", step)

Errors & limits

• 401 — missing or invalid key.
• 422 — schema violation (field map errors, empty name, non-screenable descriptor).
• 429 — rate limit; retry after the Retry-After header.
• 5xx — engine fault; every 5xx is paged and recorded in your event log.

Rate limits: 60 req/min per key on Growth, 600 on Enterprise; batch screening is uncounted for concurrent volume.

Security & compliance

• SOC 2 Type II audited; GDPR-ready with DPA, sub-processor list and EU data residency.
• Encryption in transit (TLS 1.3) and at rest (AES-256).
• Region-pinned deployment: GCC, EU or US — choose at onboarding, data never leaves your region.
• Enterprise: private cloud or fully on-premises; the engine is deterministic and runs identically with zero data egress.
• Role-based access (analyst / reviewer / MLRO / admin) with mandatory attribution on dispositions.

Determinism & reproducibility

The scoring engine is a pure function: same inputs → same score, every run, on any machine. No stochastic sampling, no drifting model weights. Each release is versioned, and every trace records the engine version that produced it — so a decision made in March can be reproduced byte-for-byte in December. This is what makes a Mizan file defensible: a regulator can re-run your logic and get your answer.

FAQ