Screening endpoint
Overview
Enigma's screening API endpoint enables you to programmatically screen customers and transactions against sanctions and other watchlists. Using your provided Enigma API key, you can submit requests directly to our screening endpoint. This guide provides details on the screening API request and response formats. All of the functionality available through our sanctions evaluation console is available to you via the API.
Once you become a customer or integration partner, we will guide you through the steps towards integrating with any watchlists of your choosing, including custom lists, as well as any case manager that suits your preference. Our API is list- and case manager-agnostic, allowing our clients to tailor our screening service to satisfy their needs, budget and volume demands. Through our screening API, we currently process over 1 billion requests per month and counting.
Screening Endpoint Specifications
Following are sample screening requests and responses to and from our Customer and Transaction screening endpoints to get you acquainted with the available inputs and outputs for screening.
To make a screening API request, ensure that you include your API key in the designated request header.
Request and Response Formats and Examples
Customer Screening REQUEST
curl --location 'https://api.enigma.com/evaluation/sanctions/screen' \
--header 'x-api-key: <YOUR API KEY>' \
--header 'Content-Type: application/json' \
--header 'Account-Name: public_evaluation' \
--data '{
"tag": "example customer screening request",
"caller_id": "<some-user-hostname-info>",
"query_type": "enigma_data",
"configuration_overrides": {
"entity": {
"alert_threshold": 0.8,
"hit_threshold": 0.5,
"max_results": 30,
"weights": {
"person_name": 3,
"dob": 1,
"country_of_affiliation": 2,
"address": 1,
"org_name": 3
}
},
"general": {
"archive_retention_days": 90,
"entity_detail_level": "minimum",
"overrides_on": true
},
"list_groups": [
"pos/sdn/all",
"pos/non_sdn/all"
],
"text": {
"alert_threshold": 0.8,
"hit_threshold": 0.5
}
},
"searches": [
{
"type": "ENTITY",
"tag": "",
"entity_description": {
"person_name": [
"John Hanafin"
],
"dob": [
"19740710"
],
"country_of_affiliation": [
"Ireland"
]
}
}
]
}'
Customer Screening RESPONSE
{
"alert": true,
"caller_id": "<some-user-hostname-info>",
"configuration_used": {
"entity": {
"alert_threshold": 0.8,
"hit_threshold": 0.5,
"max_results": 30,
"weights": {
"address": 1.0,
"country_of_affiliation": 2.0,
"dob": 1.0,
"org_name": 3.0,
"person_name": 3.0
}
},
"general": {
"archive_retention_days": 90,
"entity_detail_level": "minimum",
"overrides_on": true
},
"list_groups": [
"pos/sdn/all",
"pos/non_sdn/all"
],
"text": {
"alert_threshold": 0.8,
"hit_threshold": 0.5
}
},
"query_type": "enigma_data",
"request_id": "fed01a4a-da7e-11ee-8600-0a58a9feac02",
"request_timestamp": "2024-03-04T23:29:07.084985+00:00",
"search_results": [
{
"alert": true,
"hits": [
{
"alert": true,
"attributes": {
"country_of_affiliation": {
"id": "nationality.62652",
"index_used": 0,
"score": 1.0,
"value": "IRELAND",
"view_ids": [
"pos/sdn/all"
]
},
"dob": {
"id": "dob.62651",
"index_used": 0,
"score": 1.0,
"value": "19740710",
"view_ids": [
"pos/sdn/all"
]
},
"person_name": {
"id": "primary_name",
"index_used": 0,
"score": 0.6708,
"value": "JOHN DESMOND HANAFIN",
"view_ids": [
"pos/sdn/all"
]
}
},
"attributes_used": [
"person_name",
"dob",
"country_of_affiliation"
],
"entity": {
"id": "ofac/sdn/43085",
"url": "https://api.stage.enigma.com/evaluation/sanctions/sanctioned_entities/ofac/sdn/43085/attributes"
},
"score": 0.8354,
"total_weight_used": 6.0
}
],
"search_index": 0,
"tag": "",
"type": "ENTITY"
}
],
"tag": "example customer screening request"
}
Transaction Screening REQUEST
The request below showcases how to use customized tags within the request to fit your transaction format. This example has an originator, originator bank, recipient, recipient bank, and message field for TEXT search. Please note that unstructured text-based search (search denoted by "type": "TEXT") is not yet open for public evaluation but soon will be. Therefore, the below sample won't work as it includes a search of this type.
curl --location 'https://api.enigma.com/evaluation/sanctions/screen' \
--header 'x-api-key: <YOUR API KEY>' \
--header 'Content-Type: application/json' \
--header 'Account-Name: public_evaluation' \
--data '{
"tag": "example transaction screening request",
"query_type": "enigma_data",
"configuration_overrides": {
"entity": {
"alert_threshold": 0.8,
"hit_threshold": 0.5,
"max_results": 30,
"weights": {
"person_name": 3,
"dob": 1,
"country_of_affiliation": 2,
"address": 1,
"org_name": 3
}
},
"general": {
"archive_retention_days": 90,
"entity_detail_level": "minimum",
"overrides_on": true
},
"list_groups": [
"pos/sdn/all",
"pos/non_sdn/all"
],
"text": {
"alert_threshold": 0.8,
"hit_threshold": 0.5
}
},
"searches": [
{
"type": "ENTITY",
"tag": "originator",
"entity_description": {
"person_name": [
"John D Hanafin"
],
"country_of_affiliation": [
"Ireland"
]
}
},
{
"type": "ENTITY",
"tag": "originator bank",
"entity_description": {
"org_name": [
"Wells Fargo"
]
}
},
{
"type": "ENTITY",
"tag": "recipient",
"entity_description": {
"person_name": [
"Sandra Milena Hernandez"
],
"address": ["INVERSIONES MACARNIC PATINO Y CIA S.C.S. Pereira Risaralda Colombia"]
}
},
{
"type": "ENTITY",
"tag": "recipient bank",
"entity_description": {
"org_name": [
"Bank Sepah"
]
}
},
{
"type": "TEXT",
"tag": "transaction message",
"text": "invoice from the Edward Bazurin project"
}
]
}'
Transaction Screening RESPONSE
{
"alert": true,
"caller_id": null,
"configuration_used": {
"entity": {
"alert_threshold": 0.8,
"hit_threshold": 0.5,
"max_results": 30,
"weights": {
"address": 1.0,
"country_of_affiliation": 1.0,
"dob": 1.0,
"org_name": 1.0,
"person_name": 3.0
}
},
"general": {
"archive_retention_days": 90,
"entity_detail_level": "minimum",
"overrides_on": true
},
"list_groups": [
"pos/sdn/all",
"pos/non_sdn/all"
],
"text": {
"alert_threshold": 0.8,
"hit_threshold": 0.5
}
},
"query_type": "enigma_data",
"request_id": "f9e1adb0-68f9-11ee-89e5-0a58a9feac02",
"request_timestamp": "2023-10-12T12:22:14.352660+00:00",
"search_results": [
{
"alert": true,
"hits": [
{
"alert": true,
"attributes": {
"country_of_affiliation": {
"id": "nationality.62652",
"score": 1.0,
"value": "IRELAND",
"view_ids": [
"pos/sdn/all"
]
},
"person_name": {
"id": "primary_name",
"score": 0.7485,
"value": "JOHN DESMOND HANAFIN",
"view_ids": [
"pos/sdn/all"
]
}
},
"entity": {
"id": "ofac/sdn/43085",
"url": "http://trident.qa.atd.enigma.com/sanctioned_entities/ofac/sdn/43085"
},
"score": 0.8114
}
],
"search_index": 0,
"tag": "originator",
"type": "ENTITY"
},
{
"alert": false,
"hits": [],
"search_index": 1,
"tag": "originator bank",
"type": "ENTITY"
},
{
"alert": true,
"hits": [
{
"alert": true,
"attributes": {
"address": {
"id": "address.13159",
"score": 0.9697,
"value": "C O INVERSIONES MACARNIC PATINO Y CIA S C S PEREIRA RISARALDA COLOMBIA",
"view_ids": [
"pos/sdn/all"
]
},
"person_name": {
"id": "primary_name",
"score": 0.8305,
"value": "SANDRA MILENA HERNANDEZ ARBOLEDA",
"view_ids": [
"pos/sdn/all"
]
}
},
"entity": {
"id": "ofac/sdn/9983",
"url": "http://trident.qa.atd.enigma.com/sanctioned_entities/ofac/sdn/9983"
},
"score": 0.8653
}
],
"search_index": 2,
"tag": "recipient",
"type": "ENTITY"
},
{
"alert": true,
"hits": [
{
"alert": true,
"attributes": {
"org_name": {
"id": "primary_name",
"score": 1.0,
"value": "BANK SEPAH",
"view_ids": [
"pos/sdn/all"
]
}
},
"entity": {
"id": "ofac/sdn/25580",
"url": "https://api.stage.enigma.com/evaluation/sanctions/sanctioned_entities/ofac/sdn/25580"
},
"score": 1.0
}
],
"search_index": 3,
"tag": "recipient bank",
"type": "ENTITY"
},
{
"alert": true,
"hits": [
{
"alert": true,
"entity_attribute": {
"attribute_id": "primary_name",
"attribute_type": "PERSON_NAME",
"attribute_value": "EDUARD BASURIN",
"entity_attribute_id": 110361041,
"entity_id": "ofac/sdn/20140",
"view_id": "pos/sdn/all"
},
"score": 0.8571428571428572,
"span": {
"begin": 3,
"end": 5,
"snippet": "Edward Bazurin"
}
}
],
"search_index": 4,
"tag": "transaction message",
"type": "TEXT"
}
],
"tag": "example transaction screening request"
}
Request and Response Field Descriptions
REQUEST Body Fields
Following are descriptions for each of the critical fields applicable to the customer and transaction screening request bodies.
- tag: At the top level, this is a description or other string associated with the whole request. This is required. The sub-level “tag” within each search in searches is associated with the search and those are optional. All tags are returned in the response in their appropriate places and can help in understanding the response.
- caller_id: This is an optional way for the user to provide hostname info associated with the request. This can be helpful for troubleshooting.
- query_type: This is required and must be the name of one of your account’s existing query types. During your trial, the account will use the default “enigma_data” query_type. We can change any specific parameter upon request. Upon onboarding, a new query type can be created with the POST /configuration/ endpoint.
- searches: a list of searches. Each item in the list has:
- searches[i].type: either "ENTITY" or "TEXT"
- searches[i].tag optional, a string to associate with the search
- searches[i].entity_description OR searches[i].text depending on the type.
- The items in entity_description are the attributes of the entity being searched for — person_name, location, dob, org_name, country_of_affiliation.
RESPONSE Body Fields
Following are descriptions for each of the critical fields applicable to the customer and transaction screening response bodies.
- alert: Whether at least one of the entity scores were ≥ alert_threshold
- caller_id: Simply caller_id given in the request, if there was one
- configuration_used: The full configuration object used for the screening. A combination of the query_type’s configuration object and any configuration_overrides
- query_type: the query_type specified in the request and used for the screening
- request_id: uuid1 created on the backend at the time the request was sent
- request_timestamp: iso timestamp generated on the backend at the time the request was sent
- search_results: a list. Each item in the list corresponds to the item at the same index in searches in the request
- search_results[i].hits: a list of the hits found for the search item
- If it’s entity type:
- hits[j].attributes: hit info, broken down by attribute included in the search. Includes value and score for each
- hits[j].score: the hit’s overall score, comes from a weighted average of attributes’ individual scores based on weights
- hits[j].alert: whether the hit’s score is ≥ alert_threshold
- hits[j].entity: entity_id and lookup url for the entity the hit claims your search matched against
- If it’s text type:
- hits[j].entity_attribute: info about what your text search matched against - entity_id, some database info, etc.
- hits[j].score: the hit’s score
- hits[j].alert: whether the hit’s score ≥ alert_threshold
- hits[j].span: the word-based start and stop indices of the fragment this hit matched against
- If it’s entity type:
- search_results[i].hits: a list of the hits found for the search item
- search_results[i].search_index: index of the corresponding search, and of this result
- search_results[i].tag: shows up if there was a tag given for this search
- search_results[i].type: "ENTITY" or "TEXT"
- search_results[i].alert: whether at least one hit in hits was with score ≥ alert_threshold
Attribute Types
Person Search Type
- Person Name: full name of the individual (name type, name subtype, title honorific, first name, middle name, surname, suffix)
- DOB: individual's date of birth in yyyymmdd format
- Address: individual's street address, city, state/province, postal code
- Country of affiliation: customized field that will match against citizenship, nationality, and/or place of birth, depending on what turns up in the entity record
Organization Search Type
- Organization Name: full name of the organization (name type, name subtype, name)
- Address: organization's street address, city, state/province, postal code
- Country of affiliation: customized field that will match against citizenship and/or nationality fields in the entity record - usually the entity's country of domicile
Learn More
For more information on our Customer and Transaction Screening endpoint, integration, and pricing, please contact our sales team.
Updated about 2 months ago