stable
Screen Entity
Screen an individual or organization against sanctions lists, PEP databases, and adverse media.
POST
{AML_CORE_URL}/amlcore/api/v1/screen-entityDescription
This endpoint performs AML/KYC screening by checking a person or entity against sanctions lists, politically exposed persons (PEP) databases, and adverse media sources. Returns a structured result with match scores, source references, and entity details.
Request Body
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| fullName | string | Required | Full legal name of the person or entity to screen | — |
| dob | string | Optional | Date of birth in YYYY-MM-DD format (individuals) | — |
| documentNumber | string | Optional | Government-issued ID number (passport, tax ID, etc.) | — |
| nationalityCodes | string[] | Optional | List of ISO 3166-1 alpha-2 country codes for nationality | — |
| matchAlgorithm | string | Optional | Accepted: LOOSE, BALANCED (default), STRICT (case-insensitive) | — |
| fuzzyNameMatch | boolean | Optional | Enable fuzzy name matching (default: true) | — |
| minScoreThreshold | number | Optional | Minimum overall score (0–100) to include a match (default: 0) | — |
| watchlistCategories | string[] | Optional | Accepted values: SANCTION, PEP, ADVERSE_MEDIA, INTERNAL (case-insensitive) | — |
| entityTypes | string[] | Optional | Accepted values: INDIVIDUAL, ORGANIZATION (case-insensitive) | — |
| nameWeight | number | Optional | Override name similarity weight (0–1) | — |
| idWeight | number | Optional | Override ID similarity weight (0–1) | — |
| dobWeight | number | Optional | Override date-of-birth weight (0–1) | — |
Example Request
cURL
curl -X POST AML_CORE/amlcore/api/v1/screen-entity \
-H "Authorization: Bearer fl_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"fullName": "John Smith"
}'Example Response
JSON
{
"timestamp": "2026-04-14T12:00:00Z",
"status": 200,
"message": "Success",
"correlationId": "fl-scrn-abc123",
"data": {
"searchId": "srch_a1b2c3",
"query": {
"name": "John Smith",
"alias": null,
"threshold": 75.0
},
"totalMatches": 2,
"truncated": false,
"matches": [
{
"matchId": "match_001",
"matchedName": "John A. Smith",
"score": {
"overall": 92.5,
"nameScore": 95.0,
"idScore": null,
"dobScore": null,
"nationalityScore": null,
"algorithm": "BALANCED"
},
"sources": [
{
"type": "SANCTION_LIST",
"authority": "National Sanctions Authority",
"program": ["sanctions_list_main"],
"referenceId": "sanc-ref-001234",
"publisher": "Government Treasury Department",
"publishedDate": "2024-01-15",
"url": "https://sanctions.example.gov/list",
"sentiment": null
},
{
"type": "PEP_LIST",
"authority": "Global PEP Registry",
"program": ["pep_database"],
"referenceId": "pep-ref-567890",
"publisher": "PEP Data Consortium",
"publishedDate": "2025-06-01",
"url": null,
"sentiment": null
}
],
"entity": {
"type": "INDIVIDUAL",
"status": "ACTIVE",
"nationality": "US",
"dateOfBirth": "1985-03-15",
"positions": ["Senior Executive Officer"],
"documentNumbers": ["PASSPORT:AB1234567"],
"cryptoAddresses": null
}
},
{
"matchId": "match_002",
"matchedName": "Jonathan Smith",
"score": {
"overall": 45.0,
"nameScore": 52.0,
"idScore": null,
"dobScore": null,
"nationalityScore": null,
"algorithm": "BALANCED"
},
"sources": [
{
"type": "ADVERSE_MEDIA",
"authority": "Media Monitoring Service",
"program": ["adverse_media_monitor"],
"referenceId": "media-ref-98765",
"publisher": "Media Analytics Corp",
"publishedDate": "2026-03-22",
"url": "https://example.com/article",
"sentiment": "NEGATIVE"
}
],
"entity": {
"type": "INDIVIDUAL",
"status": null,
"nationality": null,
"dateOfBirth": null,
"positions": null,
"documentNumbers": null,
"cryptoAddresses": null
}
}
],
"screenedAt": "2026-04-14T12:00:01Z"
}
}Response Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| searchId | string | Optional | Unique identifier | srch_a1b2c3 |
| query | object | Optional | Original query | {"name":"John Smith","alias":null,"threshold":75} |
| totalMatches | integer | Optional | Total matches | 2 |
| truncated | boolean | Optional | Results truncated (max 10 returned) | false |
| matches[].matchId | string | Optional | Match ID | match_001 |
| matches[].matchedName | string | Optional | Matched watchlist name | John A. Smith |
| matches[].score | object | Optional | Score breakdown. Sub-scores are null when the input lacked that criterion. | {"overall":92.5,"nameScore":95.0,"idScore":null,"algorithm":"BALANCED"} |
| matches[].sources[] | array | Optional | Source references. Each has: type, authority, program[], referenceId, publisher, publishedDate, url, sentiment. | [{"type":"SANCTION_LIST","authority":"National Sanctions Authority","program":["sanctions_list_main"]}] |
| matches[].entity | object | Optional | Entity details. cryptoAddresses may be null. | {"type":"INDIVIDUAL","status":"ACTIVE","nationality":"US","positions":["Senior Executive Officer"]} |
| screenedAt | string | Optional | Screening timestamp | 2026-04-14T12:00:01Z |
Error Codes
| Code | Message |
|---|---|
| 400 | fullName is required |
| 422 | Invalid dob format. Use YYYY-MM-DD |
| 503 | Screening service temporarily unavailable. Retry later. |
Try It
Use the sandbox environment to test this endpoint with pre-configured test data.