Screen any user.
Against 1,300+ global lists.

# Didit AML Screening — integrate in 5 minutes

You are integrating Didit's Anti-Money Laundering (AML) Screening module into
<my_stack>. Follow these steps exactly. Every URL, header, and enum value
below is canonical — do not paraphrase or "improve" them.

AML Screening covers four lookup categories on every call:
  - Sanctions (OFAC, EU, UN, HMT, and 1,300+ more global lists)
  - Politically Exposed Persons (PEPs) — Levels 1 through 4 + RCAs
  - Adverse Media — financial-crime news, court records, regulatory press
  - Warnings and Regulatory Enforcement, Insolvency, SIP / SIE lists

The same module screens BOTH persons and companies — set the
"entity_type" parameter to "person" or "company".

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI / linked KYC)
Best when you want AML screened automatically as part of a verification
session. Run it alongside ID Verification, or chain it after a Know Your
Customer (KYC) check, or fire it on its own.

1. Create a workflow that contains the AML feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the entry
         { "feature": "AML" }     (UPPERCASE — strict enum)
   Optional per-workflow configuration:
     - match_score_threshold        (default 93)
     - approve_risk_threshold       (default 80)
     - review_risk_threshold        (default 100)
     - include_adverse_media        (default true; adds ~10s to the call)
     - include_ongoing_monitoring   (default false; +$0.07/user/year if on)
     - sanctions_categories         (subset of dataset enums)

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id),
         expected_details { first_name, last_name, date_of_birth,
                            nationality, document_number }.
   Response: session_url — redirect the user to it. If your workflow has
   only the AML feature and you already collected the identity fields,
   the session resolves server-side with no UI step.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone server-to-server API
Best when you already have the screened entity's name + identifiers and
do not want a hosted session. Synchronous response, no webhook needed.

POST https://verification.didit.me/v3/aml/
Content-Type: application/json
Headers:
  x-api-key: <your-api-key>
Body (person):
  {
    "entity_type": "person",
    "full_name": "Carmen Espanola",
    "date_of_birth": "1980-01-01",
    "nationality": "ESP",
    "document_number": "CAA000000",
    "include_adverse_media": true,
    "include_ongoing_monitoring": false
  }
Body (company):
  {
    "entity_type": "company",
    "full_name": "Acme Holdings Ltd",
    "registration_number": "12345678",
    "incorporation_country": "GBR",
    "include_adverse_media": true
  }

Response: JSON report with status, hits, scores, and a warnings array.

## 3. Webhooks (Path A and Path B ongoing monitoring)
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined", "aml.new_hit"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 4. Reading the report (both paths return the same shape)
The aml object includes:
- status: "Approved" | "Rejected" | "In Review" | "Not Started"
- total_hits: integer
- score: number 0-100 (overall AML risk score; highest non-False-Positive
  match risk score wins)
- screened_data: the inputs used for the lookup
- hits: array of matched entities. Each hit includes:
    - id, url, caption (matched display name)
    - datasets: which categories matched (PEP, PEP Level 1..4, Sanctions,
      Adverse Media, Warnings and Regulatory Enforcement, Fitness and
      Probity, SIP, SIE, Insolvency)
    - match_score (0-100, identity confidence — is it the same person)
    - risk_view.categories.score (0-100, entity risk if it IS a match)
    - sanction_matches, pep_matches, warning_matches,
      adverse_media_matches (typed arrays with list names, source URLs,
      legal basis, sanction program, sanctioning authority, publication
      dates, sentiment scores, etc.)
- warnings: Array<{ risk, log_type, short_description, long_description }>

Two-score system (the part most agents get wrong):
  1. Match Score answers "is this the same person we are screening".
     Below the match_score_threshold (default 93) the hit is a
     False Positive and excluded from the final status. At or above the
     threshold it is Unreviewed (a possible match).
  2. Risk Score answers "how risky is this entity if it IS a match".
     The session's final status comes from the highest risk score among
     non-False-Positive hits:
       - risk score below approve_risk_threshold (80)   => Approved
       - between approve and review                     => In Review
       - above review_risk_threshold (100)              => Declined

Warning codes you should branch on:
- POSSIBLE_MATCH_FOUND          (informational — at least one hit above the
                                 match threshold; review or auto-approve
                                 per your risk policy)
- COULD_NOT_PERFORM_AML_SCREENING  (KYC fields incomplete; session is held
                                 in In Review and re-triggered automatically
                                 once full_name, date_of_birth, issuing
                                 state and document_number are populated)

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: AML, ID_VERIFICATION, LIVENESS, FACE_MATCH,
  IP_ANALYSIS. The AML feature flag is AML, not AML_SCREENING.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Rejected", "In Review",
  "Not Started" (title-cased, space-separated).
- entity_type is lowercase: "person" or "company".

## 6. Ongoing monitoring
- Toggle include_ongoing_monitoring=true on the workflow or the standalone
  request to enroll the screened entity in continuous AML monitoring.
- Didit rescreens every enrolled entity DAILY against the full 1,300+
  watchlist database (sanctions, PEPs, adverse media, warnings).
- A status change (new hit above review or decline threshold) fires the
  aml.new_hit webhook, flips the session status to In Review or Declined,
  and surfaces the hit in the Business Console with full audit trail.
- Billing: $0.07 per enrolled entity per year. Toggle off at any time
  from the Business Console — billing prorates to the day.

## 7. Pricing reference (public)
- AML Screening (one-time, per person OR per company): $0.20 per check
- Ongoing AML Monitoring: $0.07 per enrolled entity per year
- Bundled inside a full KYC workflow (ID + Liveness + Face Match + IP):
  $0.33 per session — AML is an add-on at the same $0.20 standalone price
- 500 free checks every month, forever, on every account.

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test names: deterministic synthetic entities returned in sandbox
  (Approved by default; canonical "PEP test name" returns an In Review
  with a Wikidata PEP hit so you can exercise the review queue).
- Switch to live: flip the application environment toggle in the console.

When in doubt: https://docs.didit.me/core-technology/aml-screening/overview