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.

Authentication

To make a screening API request, ensure that you include your API key in the designated request header.

Request and Response Formats

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"
        ]
      }
    }
  ]
}'

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"
          },
          "score": 0.8354,
          "total_weight_used": 6.0
        }
      ],
      "search_index": 0,
      "tag": "",
      "type": "ENTITY"
    }
  ],
  "tag": "example customer screening request"
}

Transaction Screening

Text Search Availability

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.

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 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": [
          "Banco de Bogota"
        ],
        "country_of_affiliation": [
          "Colombia"
        ]
      }
    }
  ]
}'

Request and Response Field Descriptions

REQUEST Body Fields

The following table describes the critical fields applicable to the customer and transaction screening request bodies:

Field	Description	Required
tag	A description or string associated with the whole request. 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.	Yes
caller_id	An optional way for the user to provide hostname info associated with the request. This can be helpful for troubleshooting.	No
query_type	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/<query type> endpoint.	Yes
searches	A list of searches. See Search Fields table below for details.	Yes

Search Fields

Each item in the searches array contains:

Field	Description	Required
type	Either "ENTITY" or "TEXT"	Yes
tag	A string to associate with the search	No
entity_description or text	For type "ENTITY": attributes of the entity being searched for (see Entity Description Fields below). For type "TEXT": the text to search.	Yes

Entity Description Fields

The following fields can be included in the entity_description:

Field	Description
person_name	Full name of the individual
location	Location information
dob	Date of birth
org_name	Organization name
country_of_affiliation	Country affiliation information

RESPONSE Body Fields

The following table describes the critical fields in the customer and transaction screening response bodies:

Field	Description
alert	Whether at least one of the entity scores were ≥ alert_threshold
caller_id	The caller_id given in the request, if one was provided
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	Array of search results. See Search Results Fields table below

Search Results Fields

Each item in the search_results array contains:

Field	Description
hits	Array of hits found for the search item. See Hit Fields tables below
search_index	Index of the corresponding search
tag	The tag given for this search (if any)
type	"ENTITY" or "TEXT"
alert	Whether at least one hit in hits was with score ≥ alert_threshold

Entity Type Hit Fields

For hits where type is "ENTITY":

Field	Description
attributes	Hit info, broken down by attribute included in the search. Includes value and score for each
score	The hit's overall score, comes from a weighted average of attributes' individual scores based on weights
alert	Whether the hit's score is ≥ alert_threshold
entity	Entity_id and lookup url for the entity the hit claims your search matched against

Text Type Hit Fields

For hits where type is "TEXT":

Field	Description
entity_attribute	Info about what your text search matched against - entity_id, database info, etc.
score	The hit's score
alert	Whether the hit's score ≥ alert_threshold
span	The word-based start and stop indices of the fragment this hit matched against

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.