> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # AML Screening API > Screen a person or company against PEP, sanctions, warning/watchlist, and adverse-media datasets in one call. **Two-score model.** Each hit carries a `match_score` (0–100, identity confidence) and a `risk_score` (0–100, entity risk). Hits whose `match_score` is below `aml_match_score_threshold` (default **93**) are tagged `review_status: "False Positive"` and ignored for risk purposes; the highest `risk_score` among the remaining hits becomes `aml.score`. The final `aml.status` follows your thresholds: `score` > `aml_score_review_threshold` (default **100**) → `Declined`; `score` > `aml_score_approve_threshold` (default **80**) → `In Review`; otherwise `Approved`. Whenever `score` is non-zero and ≥ the approve threshold a `POSSIBLE_MATCH_FOUND` warning is added (a score of exactly 0 never warns). **Match-score weights.** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` must sum to exactly 100 (defaults 60/25/15). Components missing from the request are re-normalized away; a matching `document_number` acts as a golden key that overrides `match_score` to 100. **Latency.** Plain screenings typically complete in a few seconds. With `include_adverse_media=true` the API waits for adverse-media enrichment (an initial ~5 s pause plus up to ~25 s of polling) — configure a client timeout of **at least 60 seconds**. **Persistence.** `save_api_request` defaults to **true**: the screening is stored as a session (`request_id` works with `GET /v3/session/{sessionId}/decision/`), it appears in the console, a `status.updated` webhook fires, and hit review statuses can be updated later. With `save_api_request=false` nothing is stored and `request_id` is a transient correlation id. `include_ongoing_monitoring=true` keeps re-screening the profile and requires `save_api_request=true` (enforced with a `400`). **Billing.** One AML API credit per call, charged after a successful screening; an insufficient balance returns `403` before any screening happens. **Sandbox.** Keys from sandbox applications skip screening and billing entirely and return a static `Approved` response with zero hits. ## OpenAPI ````yaml POST /v3/aml/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/aml/: post: tags: - Standalone APIs summary: AML screening (standalone) description: >- Screen a person or company against PEP, sanctions, warning/watchlist, and adverse-media datasets in one call. **Two-score model.** Each hit carries a `match_score` (0–100, identity confidence) and a `risk_score` (0–100, entity risk). Hits whose `match_score` is below `aml_match_score_threshold` (default **93**) are tagged `review_status: "False Positive"` and ignored for risk purposes; the highest `risk_score` among the remaining hits becomes `aml.score`. The final `aml.status` follows your thresholds: `score` > `aml_score_review_threshold` (default **100**) → `Declined`; `score` > `aml_score_approve_threshold` (default **80**) → `In Review`; otherwise `Approved`. Whenever `score` is non-zero and ≥ the approve threshold a `POSSIBLE_MATCH_FOUND` warning is added (a score of exactly 0 never warns). **Match-score weights.** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` must sum to exactly 100 (defaults 60/25/15). Components missing from the request are re-normalized away; a matching `document_number` acts as a golden key that overrides `match_score` to 100. **Latency.** Plain screenings typically complete in a few seconds. With `include_adverse_media=true` the API waits for adverse-media enrichment (an initial ~5 s pause plus up to ~25 s of polling) — configure a client timeout of **at least 60 seconds**. **Persistence.** `save_api_request` defaults to **true**: the screening is stored as a session (`request_id` works with `GET /v3/session/{sessionId}/decision/`), it appears in the console, a `status.updated` webhook fires, and hit review statuses can be updated later. With `save_api_request=false` nothing is stored and `request_id` is a transient correlation id. `include_ongoing_monitoring=true` keeps re-screening the profile and requires `save_api_request=true` (enforced with a `400`). **Billing.** One AML API credit per call, charged after a successful screening; an insufficient balance returns `403` before any screening happens. **Sandbox.** Keys from sandbox applications skip screening and billing entirely and return a static `Approved` response with zero hits. operationId: post_v3aml parameters: [] requestBody: required: true content: application/json: schema: type: object required: - full_name properties: full_name: type: string description: Full name of the person or company to screen. example: Antonio Ejemplo Modelo entity_type: type: string enum: - person - company default: person description: Type of entity to screen. Defaults to `person`. date_of_birth: type: string format: date description: >- Date of birth (persons) or incorporation date (companies), `YYYY-MM-DD`. Improves match precision via the DOB weight. example: '1972-02-29' nationality: type: string description: >- ISO 3166-1 **alpha-2** country code (e.g. `ES`). Invalid codes return `400`. Improves match precision via the country weight. example: ES document_number: type: string description: >- Identity document number. Not weighted — acts as a golden key: an exact match overrides the hit's `match_score` to 100, a hard mismatch penalizes it. aml_score_approve_threshold: type: number minimum: 0 maximum: 100 default: 80 description: >- Risk-score threshold at or below which the result is `Approved`. Must be ≤ `aml_score_review_threshold` (else `400`). aml_score_review_threshold: type: number minimum: 0 maximum: 100 default: 100 description: >- Risk-score threshold above which the result is `Declined`. Scores between the two thresholds produce `In Review`. aml_name_weight: type: integer minimum: 0 maximum: 100 default: 60 description: >- Weight of name similarity in the per-hit match score. The three weights must sum to exactly 100 (else `400`). aml_dob_weight: type: integer minimum: 0 maximum: 100 default: 25 description: Weight of date of birth in the per-hit match score. aml_country_weight: type: integer minimum: 0 maximum: 100 default: 15 description: Weight of country/nationality in the per-hit match score. aml_match_score_threshold: type: integer minimum: 0 maximum: 100 default: 93 description: >- Per-hit cutoff: hits with `match_score` below this are `False Positive` (excluded from risk assessment); at or above are `Unreviewed` possible matches. include_adverse_media: type: boolean default: false description: >- Also search news media for negative coverage. Adds up to ~30 s of latency while results are gathered — use a ≥60 s client timeout. include_ongoing_monitoring: type: boolean default: false description: >- Keep re-screening this profile and push changes via webhook. Requires `save_api_request=true` (else `400`). save_api_request: type: boolean default: true description: >- Persist the screening as a session (console visibility, decision endpoint, webhooks, hit review). Set to `false` for a stateless check. vendor_data: type: string description: >- Your identifier for the screened user; echoed back and stored with the session. metadata: type: object nullable: true description: Free-form JSON stored with the request and echoed back. responses: '200': description: >- Screening completed. `aml.status` reflects your thresholds; every hit at or above the internal inclusion floor is listed in `aml.hits` with its identity `match_score`, entity `risk_score`, and a `score_breakdown` explaining the match. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- Persisted session id when `save_api_request=true` (usable with `GET /v3/session/{sessionId}/decision/`); otherwise a transient correlation UUID. aml: type: object properties: status: type: string enum: - Approved - In Review - Declined description: >- `Declined` when `score` > `aml_score_review_threshold`; `In Review` when `score` > `aml_score_approve_threshold`; `Approved` otherwise (including when no score is available). total_hits: type: integer description: Number of entries in `hits`. entity_type: type: string enum: - person - company description: Echo of the screened entity type. hits: type: array items: type: object description: >- One screening hit. `match_score` (0–100) measures identity confidence — hits below `aml_match_score_threshold` are tagged `review_status: "False Positive"` and excluded from the risk assessment; hits at or above it are `"Unreviewed"` possible matches. `risk_score` (0–100) measures how risky the matched entity is and drives the top-level `aml.score`. properties: id: type: string nullable: true description: >- Stable identifier of the matched entity in the screening datasets. url: type: string nullable: true description: >- Source URL for the matched entity, when available. match: type: boolean nullable: true description: >- Legacy exact-match flag. Prefer `match_score` + `review_status`. score: type: number nullable: true description: >- DEPRECATED weighted match score in the 0–1 range. Use `match_score` instead. match_score: type: number nullable: true description: >- Identity confidence (0–100). Compared against `aml_match_score_threshold` to split False Positives from Possible Matches. risk_score: type: number nullable: true description: >- Entity risk score (0–100). The highest `risk_score` among non-false-positive hits becomes the top-level `aml.score`. target: type: boolean nullable: true caption: type: string nullable: true description: Display name of the matched entity. datasets: type: array nullable: true items: type: string description: >- Datasets the entity appears in (e.g. `PEP`, `PEP Level 1`, sanctions list names). features: type: object nullable: true properties: type: object nullable: true description: >- Entity profile: `name`, `alias`, `notes`, `gender`, `birthDate`, `birthPlace`, `nationality`, `position`, and other biographical arrays (each nullable). rca_name: type: string nullable: true description: >- Name of the related close associate through which the entity was matched, when the hit is an RCA. pep_matches: type: array description: PEP list entries backing this hit. items: type: object properties: list_name: type: string publisher: type: string source_url: type: string description: type: string matched_name: type: string pep_position: type: string date_of_birth: type: string place_of_birth: type: string aliases: type: array items: type: string education: type: array items: type: string other_sources: type: array items: type: string sanction_matches: type: array items: type: object description: >- Sanctions list entries backing this hit (same backing-list shape as `pep_matches`, plus sanction-specific fields). warning_matches: type: array items: type: object description: Warning/watchlist entries backing this hit. adverse_media_matches: type: array description: >- Adverse-media articles. Populated only when `include_adverse_media=true`. items: type: object properties: headline: type: string summary: type: string sentiment: type: string sentiment_score: type: number source_url: type: string thumbnail: type: string nullable: true country: type: string nullable: true author_name: type: string nullable: true publication_date: type: string nullable: true adverse_keywords: type: array items: type: string other_sources: type: array items: type: string adverse_media_details: type: object nullable: true description: >- Aggregated adverse-media sentiment for the entity (`sentiment`, `sentiment_score`, `adverse_keywords` frequency map). Populated only when `include_adverse_media=true`. first_seen: type: string format: date-time nullable: true description: When the entity first appeared in the datasets. last_seen: type: string format: date-time nullable: true description: >- Most recent dataset refresh that included the entity. linked_entities: type: array description: >- Known relationships of the matched entity (family, associates, companies). items: type: object properties: name: type: array items: type: string active: type: array items: type: string status: type: array items: type: string details: type: array items: type: string relation: type: array items: type: string risk_view: type: object nullable: true description: >- Per-dimension risk breakdown (`crimes`, `countries`, `categories`, `custom_list`), each with `score`, `weightage`, `risk_level`, and a `risk_scores` map. additional_information: type: object nullable: true description: >- Free-form extra context, e.g. a `flag_summary` array explaining why the entity is flagged. review_status: type: string nullable: true enum: - False Positive - Unreviewed - Confirmed Match - Inconclusive description: >- `False Positive` — `match_score` below `aml_match_score_threshold`, excluded from risk assessment. `Unreviewed` — possible match awaiting review. `Confirmed Match` / `Inconclusive` — set manually by a reviewer (via the Business Console) on saved sessions; that review capability is not part of this spec. score_breakdown: type: object nullable: true description: >- How `match_score` was computed. Name, date of birth, and country each contribute `_score` × `_weight_normalized` points; weights are re-normalized when a component is missing from the screened data. The document number is not weighted — it acts as a 'golden key': `MATCH` overrides the score to 100, `NEUTRAL` leaves it unchanged, `HARD_MISMATCH` applies a penalty. properties: name_score: type: integer nullable: true description: Raw name similarity (0–100). name_weight: type: integer nullable: true description: Configured name weight (`aml_name_weight`). name_weight_normalized: type: number nullable: true description: Name weight after re-normalization (0–100). name_contribution: type: number nullable: true description: >- Points the name contributed to `total_score`. dob_score: type: integer nullable: true description: >- Date-of-birth score as a percentage of its weight (−100 to 100). dob_weight: type: integer nullable: true description: Configured DOB weight (`aml_dob_weight`). dob_weight_normalized: type: number nullable: true description: DOB weight after re-normalization (0–100). dob_contribution: type: number nullable: true description: Points the DOB contributed to `total_score`. country_score: type: integer nullable: true description: >- Country score as a percentage of its weight (−100 to 100). country_weight: type: integer nullable: true description: >- Configured country weight (`aml_country_weight`). country_weight_normalized: type: number nullable: true description: >- Country weight after re-normalization (0–100). country_contribution: type: number nullable: true description: >- Points the country contributed to `total_score`. document_number_match_type: type: string nullable: true enum: - MATCH - NEUTRAL - HARD_MISMATCH description: >- Golden-key result for the document number comparison. document_number_effect: type: string nullable: true description: >- Human-readable description of the document-number effect. total_score: type: integer nullable: true description: >- Final weighted match score (0–100) — mirrors `match_score`. score: type: number nullable: true description: >- Overall AML risk score (0–100): the highest `risk_score` among hits that are not False Positives. Drives `status` via the two thresholds. screened_data: type: object description: >- Echo of what was screened: `full_name`, `date_of_birth`, `nationality`, `document_number` (absent fields are `null`). properties: full_name: type: string date_of_birth: type: string nullable: true nationality: type: string nullable: true document_number: type: string nullable: true warnings: type: array items: type: object properties: feature: type: string description: Feature that raised the warning. risk: type: string description: Machine-readable risk identifier. additional_data: type: object nullable: true description: Extra context for the warning, when available. log_type: type: string description: >- `warning`, `information`, or `error` — how the risk affected the outcome. short_description: type: string description: One-line human-readable summary. long_description: type: string description: Full human-readable explanation. description: >- Contains a `POSSIBLE_MATCH_FOUND` warning whenever `score` is non-zero and ≥ `aml_score_approve_threshold` (a score of exactly 0 never warns); empty otherwise. vendor_data: type: string nullable: true description: Echo of the `vendor_data` you sent. metadata: type: object nullable: true description: Echo of the `metadata` you sent. created_at: type: string format: date-time examples: No hits (Approved): summary: Clean screening — zero hits value: request_id: d27c5509-7a66-45a9-b05e-d69d9f4c336a aml: status: Approved total_hits: 0 entity_type: person hits: [] score: 0 screened_data: full_name: Maximilian Mustermann-Doe date_of_birth: '1992-03-14' nationality: DE document_number: null warnings: [] vendor_data: user-1234 metadata: internal_ref: abc-123 created_at: '2026-06-11T10:21:07.013938+00:00' PEP hit (Approved — risk below approve threshold): summary: >- One PEP possible match; risk score 73 stays under the default approve threshold of 80 value: request_id: 0b7e7a3e-65a1-4f3d-9c7a-1de2f9a40111 aml: status: Approved total_hits: 1 entity_type: person hits: - id: kDpfszrbkDdaxpMVZw3NLg url: https://news.example.org/articles/sample match: false score: 0.93 match_score: 93 risk_score: 73 target: null caption: Antonio Ejemplo Modelo datasets: - PEP Level 1 - PEP features: null rca_name: '' first_seen: '2026-01-07T00:00:00' last_seen: '2026-01-07T00:00:00' review_status: Unreviewed properties: name: - Antonio Ejemplo Modelo - Antonio Ejemplo alias: - Antonio Ejemplo Modelo - Ejemplo Modelo, Pedro notes: - Prime Minister of Spain gender: - male birthDate: - '1972-02-29' birthPlace: - Madrid, Spain nationality: null position: null risk_view: crimes: score: 0 weightage: 20 risk_level: Low risk_scores: {} countries: score: 9.64 weightage: 30 risk_level: Low risk_scores: Spain: 25.71 categories: score: 62.5 weightage: 50 risk_level: High risk_scores: PEP: 100 PEP Level 1: 100 custom_list: {} score_breakdown: name_score: 89 name_weight: 60 name_weight_normalized: 60 name_contribution: 53.4 dob_score: 100 dob_weight: 25 dob_weight_normalized: 25 dob_contribution: 25 country_score: 100 country_weight: 15 country_weight_normalized: 15 country_contribution: 15 document_number_match_type: NEUTRAL document_number_effect: No document number provided for screening total_score: 93 pep_matches: - aliases: [] education: [] list_name: Presidency of the Government of Spain publisher: Presidency of the Government of Spain source_url: https://news.example.org/articles/sample description: >- The Presidency of the Government is the central institutional body in Spain that supports the Prime Minister and coordinates the general action of the central government. matched_name: Antonio Ejemplo Modelo pep_position: '' date_of_birth: '1972-02-29' other_sources: [] place_of_birth: Madrid, Spain sanction_matches: [] warning_matches: [] adverse_media_matches: [] adverse_media_details: null linked_entities: - name: - Maria Begona Gomez Fernandez active: [] status: [] details: [] relation: - spouse additional_information: flag_summary: - >- Antonio Ejemplo Modelo has been flagged as a Level 1 Politically Exposed Person (PEP) from Spain, serving as the President of the Government of Spain. score: 73 screened_data: full_name: Pedro Sanchez Perez-Castejon date_of_birth: '1972-02-29' nationality: ES document_number: null warnings: [] vendor_data: null metadata: null created_at: '2026-06-11T10:23:44.812000+00:00' '400': description: >- Validation error. Field-level problems return DRF's standard envelope (one array of messages per offending field); cross-field rules (weight sum, threshold ordering, monitoring-without-save) return `{"error": [...]}`. content: application/json: examples: Missing full_name: summary: '`full_name` is the only required field' value: full_name: - This field is required. Invalid nationality: summary: '`nationality` must be ISO 3166-1 alpha-2' value: nationality: - Invalid ISO 3166-1 alpha-2 country code. Weights do not sum to 100: summary: >- `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` ≠ 100 value: error: - >- AML weights must sum to 100. Current sum: 90 (name: 50, dob: 25, country: 15) Thresholds out of order: summary: Approve threshold above review threshold value: error: - >- Approve threshold (90.0) cannot be greater than review threshold (80.0) Monitoring without saving: summary: >- `include_ongoing_monitoring=true` with `save_api_request=false` value: error: - >- Ongoing monitoring can only be enabled when the API request is saved. '403': description: >- Permission denied. Returned when the `x-api-key` header is missing, malformed, revoked, or belongs to another environment — and also when the calling organization's balance cannot cover the call. Authentication failures return `403` with `{"detail": ...}`; this API never returns `401`. Credit shortfalls return `403` with `{"error": ...}` before any screening or provider call happens. content: application/json: examples: Missing or invalid API key: summary: No `x-api-key` header, or the key is invalid/revoked value: detail: You do not have permission to perform this action. Not enough credits: summary: Organization balance cannot cover the call value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Rate limit exceeded. All POST/PATCH/DELETE endpoints share a budget of 300 write requests per minute per API key. The response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` headers. content: application/json: examples: Write rate limit exceeded: summary: More than 300 write requests in the current minute value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/aml/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "full_name": "Antonio Ejemplo Modelo", "entity_type": "person", "date_of_birth": "1972-02-29", "nationality": "ES", "include_adverse_media": false, "vendor_data": "user-1234" }' - lang: python label: Python source: >- import os, requests resp = requests.post( "https://verification.didit.me/v3/aml/", headers={ "x-api-key": os.environ["DIDIT_API_KEY"], "Content-Type": "application/json", }, json={ "full_name": "Antonio Ejemplo Modelo", "entity_type": "person", "date_of_birth": "1972-02-29", "nationality": "ES", "include_adverse_media": False, "vendor_data": "user-1234", }, timeout=60, # adverse media enrichment can add ~30s ) resp.raise_for_status() print(resp.json()["aml"]["status"]) # Approved / In Review / Declined - lang: javascript label: JavaScript source: |- const res = await fetch('https://verification.didit.me/v3/aml/', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ full_name: 'Antonio Ejemplo Modelo', entity_type: 'person', date_of_birth: '1972-02-29', nationality: 'ES', include_adverse_media: false, vendor_data: 'user-1234', }), }); const data = await res.json(); console.log(data.aml.status); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````